tigerharness 0.1.0__tar.gz

tigerharness-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.lock
+.pytest_cache/
+.coverage
+htmlcov/
+htmlcov/

tigerharness-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,140 @@
+# Contributing to tigerharness
+
+## Development setup
+
+```bash
+git clone https://github.com/DingyuZhou/TigerHarness.git
+cd tigerharness
+uv sync --extra all
+```
+
+## Running tests
+
+```bash
+# All tests
+uv run pytest
+
+# With coverage report
+uv run pytest --cov=tigerharness --cov-report=term-missing
+
+# Single module
+uv run pytest tests/tiger_memory/test_lifecycle_full.py -v
+```
+
+Coverage threshold: **98.5%** (enforced in `pyproject.toml`). Current: **98.60%** (1088 tests).
+
+## Project structure
+
+```
+src/tigerharness/
+    __init__.py              Top-level package
+    cli.py                   Unified CLI entry point
+    init.py                  Project scaffolding (tigerharness init)
+    py.typed                 PEP 561 type stub marker
+    task_runner/             Iterative task execution
+        cli.py               CLI subcommands (assign, list, cancel, logs)
+        runner.py            Core iteration loop
+        notifier.py          Slack DM notifications
+        personas.py          Config-driven persona registry
+        registry.py          Task state persistence
+    slack_bridge/            Slack Socket Mode bridge
+        bridge.py            Event handler + dispatch
+        config.py            Env-var-driven config loader
+        downloader.py        File attachment download
+        notify.py            Outbound DM/file CLI
+        persistence.py       Thread -> session mapping
+    tiger_memory/            Persistent memory management
+        cli.py               CLI (init, rebuild, search, drill, pin)
+        config.py            YAML config loader
+        lifecycle.py         Bootstrap / rebuild / resummarize engine
+        briefing.py          Layered briefing rebuild
+        drill.py             Read commands (drill, tree, raw, search)
+        store.py             On-disk store + atomic write + locking
+        must_memorize.py     Scored memo table with decay
+        rag.py               Embedding-based semantic search
+        embedders.py         Pluggable embedding backends
+        frontmatter.py       YAML frontmatter parser/writer
+        sources/             Source adapters (claude_code, docs)
+        summarizers/         Summarizer backends (anthropic, mock)
+        templates/           Briefing README template
+tests/
+    task_runner/             Task runner tests
+    slack_bridge/            Slack bridge tests
+    tiger_memory/            Tiger memory tests
+    test_main_modules.py     __main__.py entrypoint tests
+examples/
+    tiger-memory.config.yaml Sample memory config (annotated)
+    personas/researcher.md   Sample persona prompt
+    env.example              Slack bridge env template
+docs/
+    DESIGN.md                Architecture decisions + migration notes
+    task-runner.md           Task runner module README
+    slack-bridge.md          Slack bridge module README
+    tiger-memory.md          Tiger memory module README
+skills/                      Claude Code SKILL.md definitions
+```
+
+## Adding a new module
+
+1. Create `src/tigerharness/<module>/` with `__init__.py`.
+2. Add tests in `tests/<module>/`.
+3. If it has CLI commands, add a `cli.py` and wire into `src/tigerharness/cli.py`.
+4. If it has optional dependencies, add an extra in `pyproject.toml`.
+5. Write a module README in `docs/<module>.md`.
+6. Run `uv run pytest --cov=tigerharness --cov-report=term-missing` and verify coverage.
+
+## Adding a custom persona
+
+1. Create a markdown file in your personas directory (e.g., `personas/analyst.md`).
+2. Set `TIGERHARNESS_PERSONAS_DIR` to point to that directory.
+3. Use `python -m tigerharness.task_runner assign --to analyst --prompt "..."`.
+
+See `examples/personas/researcher.md` for a template.
+
+## Adding a custom memory backend
+
+Tiger-memory's summarizer is pluggable:
+
+1. Subclass `tigerharness.tiger_memory.summarizers.base.Summarizer`.
+2. Implement `summarize(prompt, max_words) -> str` and `cost_estimate_usd(...)`.
+3. Register in `_build_summarizer()` in `lifecycle.py` (or propose a plugin hook).
+
+## Code style
+
+- Python 3.11+
+- Type hints on all public APIs
+- Docstrings on all modules and public functions
+- No hardcoded paths -- everything via env vars or config
+- Tests use `tmp_path` fixtures for filesystem isolation
+- Mock external services (Slack, Anthropic, subprocess) in tests
+
+## Commit conventions
+
+```
+<prefix>: <imperative summary, 72 chars max>
+
+<body>
+```
+
+Prefix: `feat:`, `fix:`, `test:`, `docs:`, `refactor:`
+
+## Running a single sub-package
+
+```bash
+# Task runner
+python -m tigerharness.task_runner --help
+
+# Slack bridge (daemon)
+python -m tigerharness.slack_bridge
+
+# Tiger memory
+tiger-memory --help
+# or: python -m tigerharness.tiger_memory.cli --help
+```
+
+## Building
+
+```bash
+uv build
+# Creates dist/tigerharness-0.1.0-py3-none-any.whl
+```

tigerharness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tigerharness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tigerharness-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: tigerharness
+Version: 0.1.0
+Summary: A generic Claude Code agent harness: iterative task execution, Slack integration, and persistent memory management.
+Project-URL: Repository, https://github.com/DingyuZhou/TigerHarness
+Project-URL: Issues, https://github.com/DingyuZhou/TigerHarness/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,anthropic,claude,harness,memory,task-runner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: aiohttp>=3.9; extra == 'all'
+Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'all'
+Requires-Dist: fastembed>=0.4; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: python-dotenv>=1.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: slack-bolt<2.0,>=1.18; extra == 'all'
+Requires-Dist: sqlite-vec>=0.1; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'anthropic'
+Provides-Extra: memory
+Requires-Dist: pyyaml>=6.0; extra == 'memory'
+Provides-Extra: memory-rag
+Requires-Dist: fastembed>=0.4; extra == 'memory-rag'
+Requires-Dist: pyyaml>=6.0; extra == 'memory-rag'
+Requires-Dist: sqlite-vec>=0.1; extra == 'memory-rag'
+Provides-Extra: memory-rag-openai
+Requires-Dist: openai>=1.0; extra == 'memory-rag-openai'
+Requires-Dist: pyyaml>=6.0; extra == 'memory-rag-openai'
+Requires-Dist: sqlite-vec>=0.1; extra == 'memory-rag-openai'
+Provides-Extra: slack
+Requires-Dist: aiohttp>=3.9; extra == 'slack'
+Requires-Dist: python-dotenv>=1.0; extra == 'slack'
+Requires-Dist: slack-bolt<2.0,>=1.18; extra == 'slack'
+Description-Content-Type: text/markdown
+
+# tigerharness
+
+A generic Claude Code agent harness: iterative task execution, Slack
+integration, and persistent memory management.
+
+## Sub-packages
+
+| Package | Description |
+|---|---|
+| `tigerharness.agent_sdk` | Backend-agnostic agent SDK. Same caller code, swappable runtimes: `claude -p` subprocess, Anthropic's `claude-agent-sdk`, OpenAI's `openai-agents` (planned). |
+| `tigerharness.task_runner` | Fire-and-forget iterative task execution. Drives a persona through N Claude turns with periodic `/compact`. |
+| `tigerharness.slack_bridge` | Slack Socket Mode bridge. Forwards DMs to a `claude -p` backend and posts replies back to the thread. |
+| `tigerharness.tiger_memory` | Persistent agent memory: archive, journal, briefing with lazy rebuild, kind-decay must-memorize, and drill-down. |
+
+## Installation
+
+```bash
+# Core (claude -p backend only; Claude Code CLI must be on PATH)
+pip install tigerharness
+
+# With the official claude-agent-sdk backend
+pip install tigerharness[anthropic]
+
+# With Slack bridge support
+pip install tigerharness[slack]
+
+# With memory support
+pip install tigerharness[memory]
+
+# With memory + RAG (local embeddings, free)
+pip install tigerharness[memory-rag]
+
+# Everything
+pip install tigerharness[all]
+```
+
+Or with uv:
+```bash
+uv add tigerharness
+uv add tigerharness --extra all
+```
+
+## Quick start
+
+### Scaffold a new project
+
+```bash
+# Create config files in the current directory
+tigerharness init --name researcher
+
+# Or with tiger-memory support
+tigerharness init --name researcher --memory
+
+# This creates:
+#   personas/researcher.md     -- edit your agent's instructions
+#   .env                       -- fill in Slack tokens
+#   tiger-memory.config.yaml   -- (only with --memory)
+```
+
+### Task runner
+
+```bash
+# 1. Point tigerharness at your personas directory
+export TIGERHARNESS_PERSONAS_DIR=./personas
+
+# 2. Assign a task (5 iterations)
+python -m tigerharness.task_runner assign \
+    --to researcher \
+    --prompt "Research the latest developments in solar energy" \
+    --iters 5
+
+# 3. Check status
+python -m tigerharness.task_runner list
+
+# 4. View logs
+python -m tigerharness.task_runner logs <task-id>
+```
+
+### Slack bridge
+
+```bash
+# 1. Fill in your Slack tokens in .env (from api.slack.com)
+#    SLACK_APP_TOKEN=xapp-...
+#    SLACK_BOT_TOKEN=xoxb-...
+#    ALLOWED_SLACK_USER_IDS=U0123ABC
+
+# 2. Run the bridge
+python -m tigerharness.slack_bridge
+```
+
+### Tiger memory
+
+```bash
+# 1. Copy the example config
+cp examples/tiger-memory.config.yaml tiger-memory.config.yaml
+# Edit: set store.root and sources.project_path
+
+# 2. Initialize the memory store
+tiger-memory --config tiger-memory.config.yaml init
+
+# 3. Bootstrap (one-time backfill from existing transcripts)
+tiger-memory --config tiger-memory.config.yaml bootstrap --dry-run
+tiger-memory --config tiger-memory.config.yaml bootstrap
+
+# 4. Rebuild (incremental, run after each session)
+tiger-memory --config tiger-memory.config.yaml rebuild
+
+# 5. Search memory
+tiger-memory --config tiger-memory.config.yaml search "solar energy"
+
+# 6. Pin a must-memorize fact
+tiger-memory --config tiger-memory.config.yaml pin "Prefers solar over wind"
+```
+
+## Configuration
+
+All paths are resolved from environment variables -- no hardcoded paths.
+
+| Variable | Default | Description |
+|---|---|---|
+| `TIGERHARNESS_STATE_DIR` | `~/.local/state/tigerharness-tasks/` | Task runner state directory |
+| `TIGERHARNESS_PERSONAS_DIR` | (none) | Directory containing `<name>.md` prompt files |
+| `TIGERHARNESS_SLACK_ENV` | `.env` | Path to slack-bridge .env file |
+| `TIGERHARNESS_AGENT_CWD` | `.` | Working directory for the Claude agent |
+| `TIGERHARNESS_AGENT_PROMPT` | (none) | Path to the agent's system prompt |
+| `TIGERHARNESS_SLACK_BRIDGE_DIR` | (none) | Path to slack-bridge service dir (for notify CLI) |
+| `TIGERHARNESS_ATTACHMENT_DIR` | `/tmp/slack-attachments` | Where to stage downloaded files |
+| `TIGER_MEMORY_CONFIG` | (none) | Path to tiger-memory YAML config |
+| `TIGER_MEMORY_CLI` | (none) | Path to tiger-memory CLI binary |
+
+## Examples
+
+See [`examples/`](examples/) for sample configs:
+- [`tiger-memory.config.yaml`](examples/tiger-memory.config.yaml) -- annotated memory config
+- [`personas/researcher.md`](examples/personas/researcher.md) -- sample persona prompt
+- [`env.example`](examples/env.example) -- Slack bridge env template
+
+## Requirements
+
+- Python 3.11+
+- For the default `claude_p` backend: the [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) (`claude`) on `PATH`.
+- For the `anthropic_sdk` backend: install with `[anthropic]` extra; pulls in [`claude-agent-sdk`](https://pypi.org/project/claude-agent-sdk/).
+
+## License
+
+MIT

tigerharness-0.1.0/README.md

@@ -0,0 +1,146 @@
+# tigerharness
+
+A generic Claude Code agent harness: iterative task execution, Slack
+integration, and persistent memory management.
+
+## Sub-packages
+
+| Package | Description |
+|---|---|
+| `tigerharness.agent_sdk` | Backend-agnostic agent SDK. Same caller code, swappable runtimes: `claude -p` subprocess, Anthropic's `claude-agent-sdk`, OpenAI's `openai-agents` (planned). |
+| `tigerharness.task_runner` | Fire-and-forget iterative task execution. Drives a persona through N Claude turns with periodic `/compact`. |
+| `tigerharness.slack_bridge` | Slack Socket Mode bridge. Forwards DMs to a `claude -p` backend and posts replies back to the thread. |
+| `tigerharness.tiger_memory` | Persistent agent memory: archive, journal, briefing with lazy rebuild, kind-decay must-memorize, and drill-down. |
+
+## Installation
+
+```bash
+# Core (claude -p backend only; Claude Code CLI must be on PATH)
+pip install tigerharness
+
+# With the official claude-agent-sdk backend
+pip install tigerharness[anthropic]
+
+# With Slack bridge support
+pip install tigerharness[slack]
+
+# With memory support
+pip install tigerharness[memory]
+
+# With memory + RAG (local embeddings, free)
+pip install tigerharness[memory-rag]
+
+# Everything
+pip install tigerharness[all]
+```
+
+Or with uv:
+```bash
+uv add tigerharness
+uv add tigerharness --extra all
+```
+
+## Quick start
+
+### Scaffold a new project
+
+```bash
+# Create config files in the current directory
+tigerharness init --name researcher
+
+# Or with tiger-memory support
+tigerharness init --name researcher --memory
+
+# This creates:
+#   personas/researcher.md     -- edit your agent's instructions
+#   .env                       -- fill in Slack tokens
+#   tiger-memory.config.yaml   -- (only with --memory)
+```
+
+### Task runner
+
+```bash
+# 1. Point tigerharness at your personas directory
+export TIGERHARNESS_PERSONAS_DIR=./personas
+
+# 2. Assign a task (5 iterations)
+python -m tigerharness.task_runner assign \
+    --to researcher \
+    --prompt "Research the latest developments in solar energy" \
+    --iters 5
+
+# 3. Check status
+python -m tigerharness.task_runner list
+
+# 4. View logs
+python -m tigerharness.task_runner logs <task-id>
+```
+
+### Slack bridge
+
+```bash
+# 1. Fill in your Slack tokens in .env (from api.slack.com)
+#    SLACK_APP_TOKEN=xapp-...
+#    SLACK_BOT_TOKEN=xoxb-...
+#    ALLOWED_SLACK_USER_IDS=U0123ABC
+
+# 2. Run the bridge
+python -m tigerharness.slack_bridge
+```
+
+### Tiger memory
+
+```bash
+# 1. Copy the example config
+cp examples/tiger-memory.config.yaml tiger-memory.config.yaml
+# Edit: set store.root and sources.project_path
+
+# 2. Initialize the memory store
+tiger-memory --config tiger-memory.config.yaml init
+
+# 3. Bootstrap (one-time backfill from existing transcripts)
+tiger-memory --config tiger-memory.config.yaml bootstrap --dry-run
+tiger-memory --config tiger-memory.config.yaml bootstrap
+
+# 4. Rebuild (incremental, run after each session)
+tiger-memory --config tiger-memory.config.yaml rebuild
+
+# 5. Search memory
+tiger-memory --config tiger-memory.config.yaml search "solar energy"
+
+# 6. Pin a must-memorize fact
+tiger-memory --config tiger-memory.config.yaml pin "Prefers solar over wind"
+```
+
+## Configuration
+
+All paths are resolved from environment variables -- no hardcoded paths.
+
+| Variable | Default | Description |
+|---|---|---|
+| `TIGERHARNESS_STATE_DIR` | `~/.local/state/tigerharness-tasks/` | Task runner state directory |
+| `TIGERHARNESS_PERSONAS_DIR` | (none) | Directory containing `<name>.md` prompt files |
+| `TIGERHARNESS_SLACK_ENV` | `.env` | Path to slack-bridge .env file |
+| `TIGERHARNESS_AGENT_CWD` | `.` | Working directory for the Claude agent |
+| `TIGERHARNESS_AGENT_PROMPT` | (none) | Path to the agent's system prompt |
+| `TIGERHARNESS_SLACK_BRIDGE_DIR` | (none) | Path to slack-bridge service dir (for notify CLI) |
+| `TIGERHARNESS_ATTACHMENT_DIR` | `/tmp/slack-attachments` | Where to stage downloaded files |
+| `TIGER_MEMORY_CONFIG` | (none) | Path to tiger-memory YAML config |
+| `TIGER_MEMORY_CLI` | (none) | Path to tiger-memory CLI binary |
+
+## Examples
+
+See [`examples/`](examples/) for sample configs:
+- [`tiger-memory.config.yaml`](examples/tiger-memory.config.yaml) -- annotated memory config
+- [`personas/researcher.md`](examples/personas/researcher.md) -- sample persona prompt
+- [`env.example`](examples/env.example) -- Slack bridge env template
+
+## Requirements
+
+- Python 3.11+
+- For the default `claude_p` backend: the [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) (`claude`) on `PATH`.
+- For the `anthropic_sdk` backend: install with `[anthropic]` extra; pulls in [`claude-agent-sdk`](https://pypi.org/project/claude-agent-sdk/).
+
+## License
+
+MIT

tigerharness-0.1.0/docs/DESIGN.md

@@ -0,0 +1,154 @@
+# tigerharness Design Document
+
+## Overview
+
+tigerharness is a standalone, open-source Python package that provides a
+generic Claude Code agent harness: iterative task execution, Slack
+integration, and persistent memory management. Extracted from the
+tigerleap workspace's `services/` directory.
+
+## Package structure decision: single package with sub-modules
+
+**Chosen: monolithic package with sub-modules** (not a uv workspace /
+monorepo with separate packages).
+
+Rationale:
+1. All three services share `agent-sdk` as a core dependency.
+2. `task-runner` already cross-references `slack-bridge` for notifications.
+3. A single `pip install tigerharness` is simpler for adopters than
+   coordinating three separate packages.
+4. Optional extras (`[slack]`, `[memory]`, `[memory-rag]`) let users
+   install only what they need.
+
+```
+tigerharness/
+  pyproject.toml          # single package, extras for slack/memory/rag
+  src/
+    tigerharness/
+      __init__.py
+      task_runner/        # iterative task execution loop
+      slack_bridge/       # Slack Socket Mode bridge to Claude
+      tiger_memory/       # persistent memory: archive, journal, briefing
+  tests/
+    task_runner/
+    slack_bridge/
+    tiger_memory/
+  skills/                 # Claude Code skill definitions (SKILL.md files)
+    assign-task/
+    slack-notify/
+    lab-notebook-quarter-roll/
+    tiger-memory-drill-down/
+    tiger-memory-search/
+  docs/
+    DESIGN.md             # this file
+    task-runner.md
+    slack-bridge.md
+    tiger-memory.md
+```
+
+## Decoupling strategy
+
+### 1. task-runner decoupling
+
+| Original coupling | Resolution |
+|---|---|
+| `WORKSPACE_ROOT = Path(__file__).parents[3]` in personas.py | Replace with config-driven persona registry. Personas defined in a YAML/Python config the user provides, not hardcoded. |
+| `tigerleap-tasks` state dir name | Rename to `tigerharness-tasks` (configurable via env). |
+| `_BRIDGE_ENV_PATH` hardcoded parents[3] path | Resolve `.env` from `SLACK_BRIDGE_ENV` env var or colocated `.env` |
+| `_SLACK_THREAD_NOTICE` hardcoded path `/home/tigerleap/projects/...` | Template that uses `TIGERHARNESS_SLACK_BRIDGE_DIR` or auto-discovers |
+| Persona system prompt files at `personas/<role>.md` | Configurable `TIGERHARNESS_PERSONAS_DIR` or pass prompt text directly |
+| Hardcoded 5 persona names (sai, chief, scout, quartermaster, inquisitor) | Ship as example/default config; users register their own personas |
+
+### 2. slack-bridge decoupling
+
+| Original coupling | Resolution |
+|---|---|
+| `_WORKSPACE_ROOT = Path(__file__).parents[3]` | Remove; all paths from env/config |
+| `_SAI_PROMPT_PATH = _WORKSPACE_ROOT / "personas" / "sai.md"` | `TIGERHARNESS_PERSONA_PROMPT` env var or config file |
+| `load_dotenv(… / "sandbox" / "slack-bridge" / ".env")` | Standard dotenv from CWD or explicit path |
+| `tiger-memory` venv path hardcoded | `TIGER_MEMORY_CLI` env var or PATH lookup |
+
+### 3. tiger-memory decoupling
+
+Already fully config-driven! No tigerleap references in code.
+Only change: move it into the `tigerharness` namespace.
+
+## Dependency map
+
+```
+tigerharness (core)
+  requires: agent-sdk (will be vendored or declared as git dep initially)
+
+tigerharness[slack]
+  adds: slack-bolt, aiohttp, python-dotenv
+
+tigerharness[memory]
+  adds: pyyaml
+
+tigerharness[memory-rag]
+  adds: fastembed, sqlite-vec
+
+tigerharness[memory-rag-openai]
+  adds: openai, sqlite-vec
+```
+
+## Configuration model
+
+All hardcoded paths are replaced with a layered config:
+
+1. **Environment variables** (highest priority):
+   - `TIGERHARNESS_STATE_DIR` — XDG state (default: `~/.local/state/tigerharness/`)
+   - `TIGERHARNESS_PERSONAS_DIR` — directory of `<name>.md` prompt files
+   - `TIGERHARNESS_SLACK_BRIDGE_DIR` — where slack-bridge runs (for notify CLI)
+   - `TIGER_MEMORY_CONFIG` — path to tiger-memory YAML config
+
+2. **Config file** (`tigerharness.yaml` or per-service configs)
+
+3. **Sensible defaults** that work out of the box for a fresh install.
+
+## Persona system redesign
+
+The original has 5 hardcoded personas. The new design:
+
+```python
+# User provides a personas.yaml or Python dict:
+personas:
+  - name: assistant
+    aliases: [ai, helper]
+    cwd: /path/to/project
+    prompt_file: personas/assistant.md  # relative to TIGERHARNESS_PERSONAS_DIR
+    permission_mode: bypassPermissions
+    disallowed_tools: ["Bash(sudo:*)"]
+```
+
+A `register_persona()` API and CLI `--persona-config` flag allow
+runtime configuration. The package ships with NO default personas
+(unlike tigerleap's 5) — users define their own.
+
+## Skills extraction
+
+Skills are Claude Code `.claude/skills/` SKILL.md files. They contain
+no executable code — just documentation for Claude to follow. We:
+
+1. Copy them into `tigerharness/skills/`
+2. Replace all hardcoded paths with generic placeholders
+3. Add an install script / docs explaining how to symlink them into a
+   project's `.claude/skills/`
+
+## Test strategy
+
+- All existing tests migrate with minimal changes (mock paths, remove
+  tigerleap assumptions).
+- New tests fill gaps in:
+  - Persona config loading (new YAML-driven system)
+  - Config resolution (env var precedence)
+  - Integration between task-runner and slack-bridge notify
+- Target: 100% line coverage via `pytest-cov`.
+
+## Migration path for tigerleap
+
+After tigerharness is stable:
+1. `tigerleap` adds `tigerharness` as a dependency
+2. `tigerleap/services/` becomes thin wrappers (or is deleted)
+3. A `tigerharness.yaml` at tigerleap root configures the personas,
+   paths, and memory