@tamng0905/builder-essential-skills 0.1.0

package/skills/session-profiler/scripts/session_profiler/trace.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import gzip
+import json
+import webbrowser
+from pathlib import Path
+
+import pandas as pd
+
+from .dataset import load, load_agents, work_dir
+
+TOC_COLORS = ["rail_response", "rail_animation", "rail_idle", "cq_build_running", "cq_build_passed", "cq_build_failed"]
+
+
+def _us(ts, origin) -> int:
+    return int((pd.Timestamp(ts) - origin).total_seconds() * 1_000_000)
+
+
+def _clip(value, limit: int = 90) -> str:
+    text = " ".join(str(value or "").split())
+    return text[: limit - 3] + "..." if len(text) > limit else text
+
+
+def _duration_seconds(row) -> float:
+    return round(float(row.duration_ms or 0) / 1000, 3)
+
+
+def _token_total(row) -> int:
+    return int(row.input_tokens + row.cache_read_input_tokens + row.cache_creation_input_tokens + row.output_tokens)
+
+
+def _event_name(row) -> str:
+    if row.event_type == "user_prompt":
+        return "Prompt: " + (_clip(row.text, 70) or "user prompt")
+    if row.event_type == "tool":
+        label = _clip(row.tool_name or "tool", 70)
+        return f"Failed: {label}" if bool(row.is_error) else label
+    if row.event_type == "inference":
+        return "Inference: " + (_clip(row.model, 60) or "model")
+    return _clip(row.event_type, 70)
+
+
+def _event_color(row) -> str:
+    if bool(row.is_error):
+        return "terrible"
+    if row.event_type == "user_prompt":
+        return "rail_response"
+    if row.event_type == "inference":
+        return "thread_state_iowait"
+    if row.event_type == "tool":
+        return "cq_build_running" if bool(row.concurrent) else "cq_build_passed"
+    return "generic_work"
+
+
+def create(data_dir=None) -> Path:
+    out = work_dir(data_dir)
+    df = load(out)
+    metadata = load_agents(out)
+    agents = metadata["agents"]
+    provider = metadata.get("provider", "unknown").title()
+    origin = df.ts.min()
+    trace = {"displayTimeUnit": "ms", "traceEvents": []}
+    ev = trace["traceEvents"]
+    ev.append({"ph": "M", "pid": 1, "tid": 0, "name": "process_name", "args": {"name": f"{provider} session profile"}})
+    ev.append({"ph": "M", "pid": 1, "tid": 1, "name": "thread_name", "args": {"name": "Session overview"}})
+    tids = {}
+    for idx, agent in enumerate(agents, 1):
+        tids[agent["id"]] = {"activity": idx * 10, "prompts": idx * 10 + 1, "tokens": idx * 10 + 2}
+        for key, suffix in [("activity", "work timeline"), ("prompts", "prompt trail"), ("tokens", "usage tokens + cost")]:
+            ev.append({"ph": "M", "pid": 1, "tid": tids[agent["id"]][key], "name": "thread_name", "args": {"name": f"{agent['name']} — {suffix}"}})
+    inf = df[df.event_type == "inference"]
+    tools = df[df.event_type == "tool"]
+    prompts = df[(df.agent_id == "main") & (df.event_type == "user_prompt")]
+    overview_name = f"{provider} session: {len(agents)} agents, {len(tools)} tool calls"
+    if not tools.empty and tools.is_error.any():
+        overview_name += f", {int(tools.is_error.sum())} failures"
+    ev.append({
+        "ph": "X",
+        "pid": 1,
+        "tid": 1,
+        "ts": 0,
+        "dur": max(1, _us(df.end_ts.max(), origin)),
+        "name": overview_name,
+        "cat": "overview",
+        "cname": "rail_idle",
+        "args": {
+            "provider": metadata.get("provider", "unknown"),
+            "session_id": metadata.get("session_id", ""),
+            "prompts": int(len(prompts)),
+            "agents": int(len(agents)),
+            "tool_calls": int(len(tools)),
+            "tool_failures": int(tools.is_error.sum()) if not tools.empty else 0,
+            "tokens": int(inf[["input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens"]].sum().sum()) if not inf.empty else 0,
+            "estimated_cost_usd": round(float(inf.estimated_cost_usd.sum()), 6) if not inf.empty else 0.0,
+        },
+    })
+    cumulative = {a["id"]: {"tokens": 0, "cost": 0.0} for a in agents}
+    for _, row in df.sort_values("ts").iterrows():
+        if row.event_type in {"inference", "tool", "user_prompt"}:
+            tid = tids[row.agent_id]["prompts" if row.event_type == "user_prompt" else "activity"]
+            ev.append({"ph": "X", "pid": 1, "tid": tid, "ts": _us(row.ts, origin), "dur": max(1, int(row.duration_ms * 1000)), "name": _event_name(row), "cat": row.event_type, "cname": _event_color(row), "args": {"wall_utc": row.ts.isoformat(), "agent": row.agent_name, "duration_s": _duration_seconds(row), "input": str(row.input_preview)[:2000], "output": str(row.output_preview)[:2000], "text": str(row.text)[:2000], "error": bool(row.is_error), "concurrent": bool(row.concurrent), "tokens": _token_total(row), "estimated_cost_usd": float(row.estimated_cost_usd)}})
+        if row.event_type == "inference":
+            tokens = _token_total(row)
+            cumulative[row.agent_id]["tokens"] += tokens
+            cumulative[row.agent_id]["cost"] += float(row.estimated_cost_usd)
+            ev.append({"ph": "C", "pid": 1, "tid": tids[row.agent_id]["tokens"], "ts": _us(row.end_ts, origin), "name": "usage tokens", "args": {"tokens": cumulative[row.agent_id]["tokens"]}})
+            ev.append({"ph": "C", "pid": 1, "tid": tids[row.agent_id]["tokens"], "ts": _us(row.end_ts, origin), "name": "usage cost", "args": {"estimated_cost_usd": round(cumulative[row.agent_id]["cost"], 6)}})
+    # Connect parent spawn -> child start and child completion -> parent result.
+    for idx, agent in enumerate(agents):
+        if agent["id"] == "main" or not agent.get("spawn_tool_use_id"):
+            continue
+        parent = df[(df.event_type == "tool") & (df.tool_use_id == agent["spawn_tool_use_id"])]
+        child = df[df.agent_id == agent["id"]]
+        if parent.empty or child.empty:
+            continue
+        spawn, child_start, child_end = parent.iloc[0], child.ts.min(), child.end_ts.max()
+        flow_id = f"spawn-{idx}"
+        ev.extend([
+            {"ph": "s", "pid": 1, "tid": tids[spawn.agent_id]["activity"], "ts": _us(spawn.ts, origin), "name": "spawn", "id": flow_id},
+            {"ph": "f", "pid": 1, "tid": tids[agent["id"]]["activity"], "ts": _us(child_start, origin), "name": "spawn", "id": flow_id, "bp": "e"},
+            {"ph": "s", "pid": 1, "tid": tids[agent["id"]]["activity"], "ts": _us(child_end, origin), "name": "completion", "id": f"done-{idx}"},
+            {"ph": "f", "pid": 1, "tid": tids[spawn.agent_id]["activity"], "ts": _us(spawn.end_ts, origin), "name": "completion", "id": f"done-{idx}", "bp": "e"},
+        ])
+    toc_path = out / "toc.json"
+    if toc_path.exists():
+        toc = json.loads(toc_path.read_text())
+        tid = 2
+        ev.append({"ph": "M", "pid": 1, "tid": tid, "name": "thread_name", "args": {"name": "Table of contents"}})
+        def add(items, depth=0):
+            for item in items:
+                try:
+                    start, end = pd.to_datetime(item["start_ts"], utc=True), pd.to_datetime(item["end_ts"], utc=True)
+                except (KeyError, ValueError):
+                    continue
+                ev.append({"ph": "X", "pid": 1, "tid": tid, "ts": _us(start, origin), "dur": max(1, _us(end, start)), "name": item.get("title", "phase"), "cat": "toc", "cname": TOC_COLORS[depth % len(TOC_COLORS)], "args": {"summary": item.get("summary", ""), "duration_s": round(_us(end, start) / 1_000_000, 3)}})
+                add(item.get("steps", []), depth + 1)
+        add(toc.get("phases", []))
+    path = out / "trace.json.gz"
+    with gzip.open(path, "wt", encoding="utf-8") as fh:
+        json.dump(trace, fh, separators=(",", ":"))
+    return path
+
+
+def open_ui() -> str:
+    webbrowser.open("https://ui.perfetto.dev")
+    return "Opened https://ui.perfetto.dev — load trace.json.gz from the parsed session directory. Review the trace for sensitive paths or text before sharing."

package/skills/session-profiler/scripts/sp

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+VENV="${SESSION_PROFILER_VENV:-$HOME/.cache/session-profiler-venv}"
+PY="$VENV/bin/python"
+
+if [ ! -x "$PY" ]; then
+  mkdir -p "$(dirname "$VENV")"
+  if command -v uv >/dev/null 2>&1; then
+    uv venv "$VENV"
+    uv pip install --python "$PY" -r "$HERE/requirements.txt"
+  else
+    python3 -m venv "$VENV"
+    "$PY" -m pip install -r "$HERE/requirements.txt"
+  fi
+fi
+
+export PYTHONPATH="$HERE${PYTHONPATH:+:$PYTHONPATH}"
+exec "$PY" -m session_profiler.cli "$@"

package/skills/session-profiler/scripts/tests/codex_home/sessions/2026/01/01/rollout-child.jsonl

@@ -0,0 +1,7 @@
+{"timestamp":"2026-01-01T00:00:01.200Z","type":"session_meta","payload":{"id":"00000000-0000-4000-8000-000000000002","cwd":"/tmp/project","source":{"subagent":{"thread_spawn":{"parent_thread_id":"00000000-0000-4000-8000-000000000001","depth":1,"agent_nickname":"Curie","agent_role":"explorer"}}},"model_provider":"openai"}}
+{"timestamp":"2026-01-01T00:00:01.300Z","type":"event_msg","payload":{"type":"task_started","turn_id":"turn-child"}}
+{"timestamp":"2026-01-01T00:00:01.400Z","type":"turn_context","payload":{"turn_id":"turn-child","model":"gpt-5.6-luna","cwd":"/tmp/project"}}
+{"timestamp":"2026-01-01T00:00:01.500Z","type":"event_msg","payload":{"type":"user_message","message":"Inspect the failure"}}
+{"timestamp":"2026-01-01T00:00:02Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"Found it"}],"internal_chat_message_metadata_passthrough":{"turn_id":"turn-child"}}}
+{"timestamp":"2026-01-01T00:00:02.100Z","type":"event_msg","payload":{"type":"token_count","info":{"last_token_usage":{"input_tokens":50,"cached_input_tokens":10,"output_tokens":5,"total_tokens":55}}}}
+{"timestamp":"2026-01-01T00:00:02.200Z","type":"event_msg","payload":{"type":"task_complete","turn_id":"turn-child","duration_ms":900}}

package/skills/session-profiler/scripts/tests/codex_home/sessions/2026/01/01/rollout-root.jsonl

@@ -0,0 +1,10 @@
+{"timestamp":"2026-01-01T00:00:00Z","type":"session_meta","payload":{"id":"00000000-0000-4000-8000-000000000001","cwd":"/tmp/project","source":"cli","model_provider":"openai"}}
+{"timestamp":"2026-01-01T00:00:00.100Z","type":"event_msg","payload":{"type":"task_started","turn_id":"turn-1"}}
+{"timestamp":"2026-01-01T00:00:00.200Z","type":"turn_context","payload":{"turn_id":"turn-1","model":"gpt-5.6-sol","cwd":"/tmp/project"}}
+{"timestamp":"2026-01-01T00:00:00.300Z","type":"event_msg","payload":{"type":"user_message","message":"Investigate with a subagent"}}
+{"timestamp":"2026-01-01T00:00:01Z","type":"response_item","payload":{"type":"function_call","name":"collaboration.spawn_agent","call_id":"call-spawn","arguments":"{\"task_name\":\"inspect\"}","internal_chat_message_metadata_passthrough":{"turn_id":"turn-1"}}}
+{"timestamp":"2026-01-01T00:00:01.100Z","type":"event_msg","payload":{"type":"token_count","info":{"last_token_usage":{"input_tokens":100,"cached_input_tokens":40,"output_tokens":20,"total_tokens":120}}}}
+{"timestamp":"2026-01-01T00:00:03Z","type":"response_item","payload":{"type":"function_call_output","call_id":"call-spawn","output":"{\"thread_id\":\"00000000-0000-4000-8000-000000000002\"}","internal_chat_message_metadata_passthrough":{"turn_id":"turn-1"}}}
+{"timestamp":"2026-01-01T00:00:04Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"Inspection complete"}],"internal_chat_message_metadata_passthrough":{"turn_id":"turn-1"}}}
+{"timestamp":"2026-01-01T00:00:04.100Z","type":"event_msg","payload":{"type":"token_count","info":{"last_token_usage":{"input_tokens":120,"cached_input_tokens":50,"output_tokens":10,"total_tokens":130}}}}
+{"timestamp":"2026-01-01T00:00:04.200Z","type":"event_msg","payload":{"type":"task_complete","turn_id":"turn-1","duration_ms":4100}}

package/skills/session-profiler/scripts/tests/fixture/main/subagents/agent-abc.jsonl

@@ -0,0 +1,2 @@
+{"type":"assistant","timestamp":"2026-01-01T00:00:02.500Z","message":{"id":"sm1","model":"claude-test","content":[{"type":"text","text":"Inspecting"}],"usage":{"input_tokens":25,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"output_tokens":3}},"uuid":"sa1","isSidechain":true}
+{"type":"assistant","timestamp":"2026-01-01T00:00:04Z","message":{"id":"sm2","model":"claude-test","content":[{"type":"text","text":"Found it"}],"usage":{"input_tokens":30,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"output_tokens":4}},"uuid":"sa2","isSidechain":true}

package/skills/session-profiler/scripts/tests/fixture/main/subagents/agent-abc.meta.json

@@ -0,0 +1 @@
+{"agentType":"Explore","description":"Inspect failure","name":"build-inspector","toolUseId":"spawn-1","spawnDepth":1}

package/skills/session-profiler/scripts/tests/fixture/main.jsonl

@@ -0,0 +1,7 @@
+{"type":"user","timestamp":"2026-01-01T00:00:00Z","message":{"role":"user","content":"Investigate the build"},"uuid":"u1"}
+{"type":"assistant","timestamp":"2026-01-01T00:00:01Z","message":{"id":"m1","model":"claude-test","content":[{"type":"thinking","thinking":"I should inspect it"}],"usage":{"input_tokens":100,"cache_read_input_tokens":20,"cache_creation_input_tokens":10,"output_tokens":5}},"uuid":"a1"}
+{"type":"assistant","timestamp":"2026-01-01T00:00:02Z","message":{"id":"m1","model":"claude-test","content":[{"type":"tool_use","id":"tool-1","name":"Bash","input":{"command":"make test"}}],"usage":{"input_tokens":100,"cache_read_input_tokens":20,"cache_creation_input_tokens":10,"output_tokens":10}},"uuid":"a2"}
+{"type":"assistant","timestamp":"2026-01-01T00:00:02.100Z","message":{"id":"m1","model":"claude-test","content":[{"type":"tool_use","id":"spawn-1","name":"Agent","input":{"description":"Inspect failure"}}],"usage":{"input_tokens":100,"cache_read_input_tokens":20,"cache_creation_input_tokens":10,"output_tokens":15}},"uuid":"a3"}
+{"type":"user","timestamp":"2026-01-01T00:00:05Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"tool-1","is_error":true,"content":"compile failed"}]},"toolUseResult":{"isError":true},"uuid":"r1"}
+{"type":"user","timestamp":"2026-01-01T00:00:06Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"spawn-1","content":"agent result"}]},"toolUseResult":{},"uuid":"r2"}
+{"type":"assistant","timestamp":"2026-01-01T00:00:07Z","message":{"id":"m2","model":"claude-test","content":[{"type":"text","text":"The build failed."}],"usage":{"input_tokens":50,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"output_tokens":8}},"uuid":"a4"}

package/skills/session-profiler/scripts/tests/test_fixture.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+import gzip
+import json
+import os
+import tempfile
+
+from session_profiler.analyses import brief
+from session_profiler.dataset import load, load_agents, parse
+from session_profiler.trace import create
+
+
+fixture = Path(__file__).parent / "fixture" / "main.jsonl"
+with tempfile.TemporaryDirectory() as tmp:
+    out = parse(fixture, tmp)
+    df = load(out)
+    agents = load_agents(out)["agents"]
+    assert len(agents) == 2
+    assert agents[1]["parent_agent_id"] == "main"
+    m1 = df[(df.event_type == "inference") & (df.message_id == "m1")].iloc[0]
+    assert m1.output_tokens == 15, "usage must use final message snapshot exactly once"
+    assert len(df[(df.event_type == "tool") & df.concurrent]) == 2
+    assert bool(df[(df.event_type == "tool") & (df.tool_use_id == "tool-1")].iloc[0].is_error)
+    assert "## At a glance" in brief(out)
+    trace_path = create(out)
+    assert trace_path.exists()
+    with gzip.open(trace_path, "rt", encoding="utf-8") as fh:
+        trace = json.load(fh)
+    names = {event.get("name") for event in trace["traceEvents"]}
+    track_names = {event.get("args", {}).get("name") for event in trace["traceEvents"]}
+    assert "Session overview" in track_names
+    assert "usage tokens" in names
+print("fixture ok")
+
+codex_home = Path(__file__).parent / "codex_home"
+codex_fixture = codex_home / "sessions" / "2026" / "01" / "01" / "rollout-root.jsonl"
+previous = os.environ.get("CODEX_HOME")
+os.environ["CODEX_HOME"] = str(codex_home)
+try:
+    with tempfile.TemporaryDirectory() as tmp:
+        out = parse(codex_fixture, tmp)
+        df = load(out)
+        metadata = load_agents(out)
+        assert metadata["provider"] == "codex"
+        assert len(metadata["agents"]) == 2
+        assert metadata["agents"][1]["parent_agent_id"] == "main"
+        assert metadata["agents"][1]["spawn_tool_use_id"] == "call-spawn"
+        first = df[(df.event_type == "inference") & (df.agent_id == "main")].iloc[0]
+        assert first.input_tokens == 60 and first.cache_read_input_tokens == 40
+        assert first.estimated_cost_usd > 0
+        assert df[df.event_type == "tool"].iloc[0].duration_ms == 2000
+        assert "Provider: `codex`" in brief(out)
+        assert create(out).exists()
+finally:
+    if previous is None:
+        os.environ.pop("CODEX_HOME", None)
+    else:
+        os.environ["CODEX_HOME"] = previous
+print("codex fixture ok")

package/skills/validate-market/README.md

@@ -0,0 +1,27 @@
+# Validate Market
+
+<p align="center">
+  <img src="../../assets/skill-cards/validate-market.svg" alt="validate-market skill card" width="100%">
+</p>
+
+Run an honest market-fit and viability audit that compares competitors, tests
+the case for the idea, and ends with clear pass, middle, or kill criteria.
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill validate-market
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill validate-market --project
+```
+
+Restart Claude Code or Codex, then ask it to audit a product, market, or
+business idea before you invest more time.
+
+See the full workflow in [SKILL.md](SKILL.md).

package/skills/validate-market/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: validate-market
+description: >-
+  Run an honest market-fit and viability audit of any project or idea and produce
+  a decision doc, not code. Use when someone asks "is this viable as a business",
+  "audit the market fit", "make the case and compare to competitors", "should I
+  apply to YC or bootstrap", or wants to validate a project, product, or market
+  before investing more time. Gathers verifiable traction data first, researches
+  the competitive field, gets an independent cold read, writes a doc with
+  pre-committed pass/middle/kill criteria and a concrete week-1 assignment, then
+  hardens it with an adversarial review loop.
+compatibility: claude-code
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - WebSearch
+  - WebFetch
+  - Agent
+  - AskUserQuestion
+---
+
+# Validate a project / market
+
+You are running a validation audit. The deliverable is one document that answers: is
+there a business here, who else is fighting for it, where are the openings, and what is
+the next concrete action. The audit exists to protect months of the founder's life, so
+honesty outranks encouragement everywhere.
+
+**Hard gate: no implementation.** No code, no scaffolding, no renames, no site changes.
+The only output is the doc (plus its adversarial review). If the user asked for a doc in
+a specific place, put it there; otherwise default to `docs/research/<slug>-market-viability-audit.md`
+in a repo, or `./<slug>-market-viability-audit.md` outside one.
+
+## Posture (non-negotiable)
+
+- **Interest is not demand.** Stars, waitlists, compliments, and "that's interesting"
+  count for nothing. Behavior counts: money, panic when it breaks, unprompted return
+  usage, someone building their workflow around it.
+- **The status quo is competitor #1.** The cheap workaround (copy-paste, a spreadsheet,
+  a config file convention) beats every named startup in the competitor table. Always
+  list it first and price what it costs the user today.
+- **Take a position on everything.** Never write "there are many ways to think about
+  this" or "that could work". Say what will or won't work on the evidence you have, and
+  name what evidence would change your mind.
+- **Papercut vs bleeding wound.** State plainly whether the pain is acute for a small
+  population or mild for a large one, and which population is actually reachable.
+- **Lead with the disconfirming evidence.** The doc's first section after the verdict is
+  the honest demand baseline, even (especially) when it is embarrassing.
+
+## Phase 0: Ground truth before opinion
+
+Collect verifiable numbers before writing a single judgment. Do not skip this; it is
+what separates an audit from a vibe.
+
+- Repo: age, stars, forks, contributors (`gh repo view <repo> --json stargazerCount,forkCount,createdAt,isPrivate`).
+- Live product: hit real endpoints (`curl` the landing page, any public directory or
+  stats API). Distinguish "deployed" from "used".
+- Any analytics, revenue, waitlist, install counts the user can show. Ask if not obvious.
+- Apply the bar: **would anyone outside the project be upset if it disappeared
+  tomorrow?** Write the answer down. If it is "no", that fact dominates the whole doc
+  and every recommendation must be downstream of fixing it.
+
+## Phase 1: Problem and wedge
+
+- State the problem in the founder's own words; quote them. The founder's phrasing
+  usually reveals the wedge better than the pitch does.
+- Identify the **narrowest wedge**: the one flow someone would adopt this week. One
+  sentence, verb first ("move X from A to B in 10 seconds"). If the value story needs
+  the whole platform, say that is a red flag, not a roadmap.
+- Name the **target user as a findable human**: role, where they hang out, what they
+  already pay for. "Developers" or "enterprises" is a filter, not a person.
+
+## Phase 2: Landscape research
+
+Use WebSearch with **generalized category terms**, never the product's name or any
+stealth details. Run at least these four searches and read the top results:
+
+1. Standards and platform state of the category ("<category> protocol landscape <year>").
+2. Funding and startups in the category ("<category> startups <year> funding").
+3. Direct adjacent products solving the same wedge ("<the wedge, described generically> tool").
+4. What incumbents absorbed recently ("<big platform> <category> features <year>").
+
+Synthesize three things explicitly:
+
+- **Who owns the lane** the wedge sits in, and whether it is genuinely open.
+- **Feature or company?** Could a platform above (the IDE, the OS, the incumbent chat
+  tool, the lab) absorb this in one release? Name the absorption clock honestly.
+- **Is the timing argument already won?** If the market no longer needs educating,
+  that cuts both ways: no education cost, but the obvious framing is taken.
+
+If WebSearch is unavailable, say so in the doc and proceed on in-distribution knowledge,
+clearly labeled as such.
+
+## Phase 3: Premises
+
+Write 3 to 5 premises the whole recommendation rests on. Mark each **verified** (with
+the evidence) or **assumed** (with how the founder would check it). Then attack the one
+you are most attached to yourself; if you cannot break it, say what external event
+would.
+
+## Phase 4: Independent cold read
+
+Get a second opinion that has not seen your reasoning:
+
+- If `codex` is on PATH: assemble a structured context block (product, stage and demand
+  evidence, founder's stated problem, landscape summary, premises) into a temp file and
+  run `codex exec` read-only against it with these asks: (1) steelman the strongest
+  version, (2) quote the one detail that reveals what to actually build, (3) name one
+  premise that is wrong and the evidence that would prove it, (4) a 48-hour plan with
+  channels, metrics, and kill criteria.
+- Otherwise: dispatch a fresh subagent (Agent tool) with the same prompt. Fresh context
+  is the point; do not paste your own conclusions.
+
+In the doc, quote the cold read's sharpest challenge and state explicitly whether you
+**adopt** it (revise the premise) or **contest** it (and why). Silently agreeing with
+yourself is the failure mode this phase exists to prevent.
+
+## Phase 5: Write the doc
+
+Structure (adapt names, keep the order; verdict first, evidence before judgment):
+
+1. **Header + verdict up front.** One paragraph: is there a business here, what is the
+   binding constraint, what to do next. No hedging.
+2. **Problem statement.**
+3. **Demand evidence (the honest part).** External evidence first, internal second,
+   clearly separated. Include the "would anyone be upset?" answer.
+4. **Status quo.** The workarounds and what they cost. Papercut-or-wound verdict.
+5. **Target user and narrowest wedge.**
+6. **Market and timing.** The 2-4 numbers that matter, sourced.
+7. **Competitive field.** A table: player, what it is, overlap, real threat (with the
+   status quo as row 1 and a one-line "why" in every threat cell). Then 1-3 structural
+   observations, including the feature-vs-company question.
+8. **Strengths.** Only real, verifiable ones. "Founder-problem fit" counts; "great
+   tech" only counts if it changes distribution or cost structure.
+9. **Weaknesses and risks.** Include the ones the founder will not enjoy reading
+   (naming/trademark, platform absorption, solo-founder, undefined pricing). For each,
+   say what to do about it and what it costs.
+10. **Premises** (from Phase 3, with the cold-read revision applied).
+11. **Cross-model perspective** (from Phase 4, positions preserved).
+12. **Approaches considered.** 2-3, always including a **minimal validation sprint**
+    (weeks, near-zero cost, outreach-first) and usually a **lateral repositioning**.
+    Effort, risk, pros, cons, what existing assets each reuses.
+13. **Recommendation.** Pick one. If the honest answer is "sequence, don't choose",
+    give the sequence with dates.
+14. **Business model sketch**, explicitly deferred until after validation. Name the
+    closest working analogy (e.g. the Tailscale playbook) rather than inventing tiers
+    from nothing.
+15. **Open questions**, each with where its answer will come from.
+16. **Success criteria: three bands, pre-committed** (see rigor checklist below).
+17. **The assignment.** One concrete real-world action for this week. Not "go build";
+    an outreach or observation action with names and counts.
+
+### Rigor checklist for the pre-committed criteria
+
+These are the holes adversarial review reliably finds. Close them before review:
+
+- **Every branch has a consequence, including kill.** "Kill (or re-frame)" is not a
+  decision. Pass, middle, and kill each name the next action and its deadline.
+- **Band precedence is explicit.** Mixed results happen; say which band wins (e.g.
+  "kill conditions are evaluated first").
+- **Denominators are fixed.** "Up to 100 asks" plus "fewer than 5 replies" is elastic;
+  add a minimum-effort precondition ("kill is valid only if 80+ asks were sent, else
+  the verdict is insufficient effort, extend one week").
+- **Terms are defined.** "Serious reply", "real conversation", "active user" each get
+  one defining line where they are used as triggers.
+- **Calendar math closes.** If the recommendation targets an external deadline (a
+  batch application, a launch window), the sprint end date plus writing time must land
+  before it. Do the arithmetic in the doc.
+- **Measurement exists.** If a criterion needs instrumentation, verifying that
+  instrumentation is a named week-1 task, with a self-report fallback.
+- **Week 1 is schedulable.** Cold outreach has reply latency; targets for week 1 are
+  "scheduled", not "completed". State the founder-availability assumption (full-time
+  vs nights-and-weekends) and give the part-time variant.
+- **Outreach measures the market, not the founder's DM skills.** Require 2+ channels
+  and absolute count bars, not conversion rates.
+
+## Phase 6: Adversarial review loop
+
+1. Dispatch a fresh subagent (Agent tool) that reads only the doc, not this
+   conversation. Have it review 5 dimensions: completeness (are all promised questions
+   answered), consistency (do sections contradict, does the timeline survive its own
+   calendar), clarity (could the founder act without asking anything), scope (audit
+   only, no padding), feasibility (executable by this founder in the stated time).
+   Ask for a numbered issue list and a 1-10 score. Tell it not to fact-check external
+   market claims, only internal logic.
+2. Fix every real issue in the doc. Push back in the doc itself where the reviewer is
+   wrong, do not silently drop findings.
+3. Re-dispatch once. Stop after two re-reviews or when new findings are cosmetic;
+   record any surviving disagreements in the doc under "Reviewer concerns".
+4. Report to the user: rounds run, issues found and fixed, final score.
+
+## Closing
+
+End with, in the final message: the verdict in two sentences, the doc's location, the
+three-band decision rule, and the week-1 assignment. If the founder profile fits (real
+problem, domain expertise, agency), say so plainly and point at the relevant next step
+(accelerator application, design-partner outreach), but only when the evidence in the
+doc supports it. No congratulations for work the market has not yet validated.

package/skills/write-blog/README.md

@@ -0,0 +1,27 @@
+# Write Blog
+
+<p align="center">
+  <img src="../../assets/skill-cards/write-blog.svg" alt="write-blog skill card" width="100%">
+</p>
+
+Write and ship a human-sounding blog post that targets search traffic, avoids
+keyword cannibalization, and connects the finished post to the project site.
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill write-blog
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill write-blog --project
+```
+
+Restart Claude Code or Codex, then ask it to draft, edit, or publish a blog
+post for the project.
+
+See the full workflow in [SKILL.md](SKILL.md).