threadroot 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to Threadroot will be documented here.
 
 Threadroot follows semantic versioning after the first public release. While `0.x`, minor versions may include breaking changes as the harness format settles.
 
+## 0.1.2 - One-command bootstrap and session start
+
+### Added
+
+- `threadroot bootstrap` as the simple first-run command for global agent setup, local-only harness initialization, health checks, and initial context.
+- `threadroot start "<task>"` as the daily agent-session command for doctor, status, task context, and Threadroot command discovery.
+- Package smoke coverage for the new bootstrap/start flow.
+
+### Changed
+
+- The generated agent bootstrap prompt now uses `threadroot bootstrap --yes` and `threadroot start "<task>"` instead of spelling out lower-level setup commands.
+- README quickstart now leads with the simplified bootstrap/start flow.
+
+## 0.1.1 - Clean setup and global agent bootstrap
+
+### Changed
+
+- `threadroot init` now creates a local-only `.threadroot/` harness by default.
+- Missing MCP config is now a doctor hint instead of a warning for local-only projects.
+- Bootstrap prompts now ask before writing project-local MCP config or provider exposure files.
+
+### Added
+
+- `threadroot expose` for thin project skill shims across Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Antigravity, and OpenCode.
+- `threadroot setup --global` for one-time machine-level Threadroot skills across supported agents.
+- Codex global setup support for `~/.agents/skills/threadroot/SKILL.md`, `~/.codex/AGENTS.md`, and optional `~/.codex/config.toml` MCP config.
+- Dry-run, check, undo, force, and MCP options for global setup.
+
 ## 0.1.0 - Initial OSS alpha
 
 ### Added

package/README.md

@@ -1,8 +1,8 @@
 # Threadroot
 
-Threadroot is **git for your AI agent harness**: you author skills, rules, tools, and
-memory once in a canonical `.threadroot/` directory, and Threadroot compiles them into
-every vendor format (AGENTS.md, Claude, Copilot, Cursor) so your agents stay in sync.
+Threadroot is **git for your AI agent harness**: you author skills, rules, tools,
+memory, connections, and agent setup once in a canonical `.threadroot/` directory.
+Provider-specific files are opt-in, thin exposure shims.
 
 It is local-first: a `tr` CLI for humans and CI, plus a local MCP server that exposes the
 same harness to coding agents. V1 does not require a cloud account, API key, or hosted
@@ -13,19 +13,17 @@ service.
 Run Threadroot without adding it to your project:
 
 ```bash
-pnpm dlx threadroot init
+npx threadroot bootstrap --yes
 # or
-npx threadroot init
-# or, explicitly with npm exec
-npm exec --package=threadroot -- threadroot init
+pnpm dlx threadroot bootstrap --yes
+# or
+npm exec --package=threadroot -- threadroot bootstrap --yes
 ```
 
 After initialization:
 
 ```bash
-threadroot doctor
-threadroot context "write tests"
-threadroot mcp setup --write
+threadroot start "write tests"
 ```
 
 For local development on Threadroot itself:
@@ -39,12 +37,9 @@ node dist/index.js --help
 ## Quick start
 
 ```bash
-tr init                 # detect the repo, scaffold a harness, import existing
-                        # vendor files once, and compile
-tr status               # authored objects vs compiled outputs, with drift
-tr context "write tests" # task-relevant skills, rules, tools, and memory
-tr doctor               # health check for harness validity, drift, MCP hints, tool trust
-tr diff                 # line diff between canonical sources and vendor files
+tr bootstrap --yes      # one-time machine setup + local-only .threadroot/
+tr start "write tests"  # doctor, status, relevant context, and command map
+tr expose codex         # optional: write a thin project skill shim for Codex
 ```
 
 `threadroot` is the full name; `tr` is the short alias.
@@ -52,7 +47,11 @@ tr diff                 # line diff between canonical sources and vendor files
 ## CLI surface
 
 ```bash
-tr init [--force] [--no-import] [--profile <p>] [--adapters <list>]
+tr bootstrap [--yes] [--agent <list>] [--task <task>] [--mcp] [--expose <list>]
+tr start ["<task>"]
+tr setup --global [--agent <list>] [--dry-run] [--check] [--undo] [--mcp]
+tr init [--force] [--no-import] [--profile <p>] [--adapters <list>] [--expose <list>]
+tr expose [agent|all] [--dry-run] [--check] [--undo] [--force]
 tr status
 tr diff
 tr doctor
@@ -91,9 +90,53 @@ The canonical, vendor-neutral source of truth:
   lock.json             # provenance for installed objects (commit SHA + integrity)
 ```
 
-`tr compile` turns the harness into the big-four vendor formats. Hand-authored prose in a
+By default, `tr init` keeps the repo clean and writes only `.threadroot/`. `tr compile`
+turns the harness into legacy vendor instruction formats only when adapters are enabled
+in `harness.yaml` or when you run `tr compile --adapter <name>`. Hand-authored prose in a
 vendor file is preserved; Threadroot only owns the block it marks as generated.
 
+## Bootstrap, global setup, and exposure
+
+The simple path is:
+
+```bash
+tr bootstrap --yes
+tr start "current task"
+```
+
+Without `--yes`, `tr bootstrap` prints a dry-run plan. With `--yes`, it installs global
+agent bootstrap skills, initializes `.threadroot/` if needed, runs doctor, and prints
+task context. It does not write provider-specific project files unless you pass
+`--expose`.
+
+Global setup installs a tiny `threadroot` skill into supported agent user-skill
+directories so agents know to call `threadroot bootstrap --yes` when setup is missing
+and `threadroot start "<task>"` when they see `.threadroot/`.
+
+Supported global skill targets:
+
+| Agent | Project exposure path | Global setup path |
+| --- | --- | --- |
+| Codex | `.agents/skills/` | `~/.agents/skills/` |
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
+| GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |
+| Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
+| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
+| Antigravity | `.agent/skills/` | `~/.gemini/antigravity/skills/` |
+| OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
+
+Use project exposure only when you want repo-local native skill discovery:
+
+```bash
+tr expose codex
+tr expose all
+tr expose all --undo
+```
+
+`tr expose` writes one managed `threadroot/SKILL.md` shim per provider. It does not copy
+every Threadroot skill into provider directories.
+
 ## Built-in content
 
 `tr init` seeds a useful harness on an empty repo:
@@ -103,7 +146,9 @@ vendor file is preserved; Threadroot only owns the block it marks as generated.
 - **Starter tools:** wrapped from the repo's detected command surface (scripts, Make/just),
   auto-added to `tools.allow`.
 - **Profile presets:** node-cli, web, python, etc. (detected by the scanner).
-- **Adapters:** agents, claude, copilot, cursor enabled by default.
+- **Adapters:** disabled by default to keep new repos local-only; use `tr expose` for
+  skill-compatible providers or `tr compile --adapter <name>` for legacy instruction
+  files.
 
 Modern skills use the Agent Skills-style folder shape:
 
@@ -193,7 +238,7 @@ Threadroot runs a local MCP server over stdio that exposes the harness to agents
 ```bash
 tr mcp
 tr mcp setup            # print config snippets and a pasteable agent bootstrap prompt
-tr mcp setup --write    # write project-local MCP config for supported agents
+tr mcp setup --write    # opt-in: write project-local MCP config for supported agents
 ```
 
 Tools: `context`, `skills_list`, `skills_get`, `tools_list`, `tools_check`, `tools_run`,
@@ -201,8 +246,8 @@ Tools: `context`, `skills_list`, `skills_get`, `tools_list`, `tools_check`, `too
 `memory_append`, `status`, `doctor`.
 
 `tr mcp setup` also prints a copy/paste agent prompt that follows the real CLI flow:
-check availability, run `threadroot init` when needed, inspect `status`, review `diff` on
-drift, and optionally write MCP config.
+check availability, run `threadroot bootstrap --yes`, run `threadroot start "<task>"`,
+and ask before writing project-local MCP config.
 
 ## Profiles
 
@@ -242,7 +287,9 @@ THREADROOT_ROOT="$(pwd)"
 TMP_REPO="$(mktemp -d /tmp/threadroot-smoke.XXXXXX)"
 rsync -a --exclude .git --exclude node_modules --exclude dist ./ "$TMP_REPO/"
 cd "$TMP_REPO"
-node "$THREADROOT_ROOT/dist/index.js" init --no-import
+HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" bootstrap --yes --agent codex --no-import
+HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" start "write tests"
+node "$THREADROOT_ROOT/dist/index.js" expose codex
 node "$THREADROOT_ROOT/dist/index.js" status
 node "$THREADROOT_ROOT/dist/index.js" context "write tests"
 node "$THREADROOT_ROOT/dist/index.js" skills validate