tau-biggz 0.1.3__tar.gz

tau_biggz-0.1.3/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @alejandro-ao

tau_biggz-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: .python-version
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev --locked
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Run Ruff lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Run mypy
+        run: uv run mypy
+
+  docs:
+    name: Documentation build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "0.152.2"
+          extended: true
+
+      - name: Build documentation
+        run: hugo --minify
+
+      - name: Build search index
+        run: npx --yes pagefind@latest --site public

tau_biggz-0.1.3/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+defaults:
+  run:
+    working-directory: website
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "0.152.2"
+          extended: true
+
+      - name: Build documentation
+        run: hugo --minify
+
+      - name: Build search index
+        run: npx --yes pagefind@latest --site public
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: website/public
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

tau_biggz-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish Python package
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

tau_biggz-0.1.3/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.mypy_cache/
+
+# Virtual environments
+.venv
+
+# Hugo docs site (website/)
+website/public/
+website/resources/
+website/.hugo_build.lock
+# Local Pi runtime state
+.atl/

tau_biggz-0.1.3/.python-version

@@ -0,0 +1 @@
+3.12

tau_biggz-0.1.3/.tau/skills/skill-creator/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: skill-creator
+description: "Trigger: create skill, new skill, crear skill, make extension, new extension, crear extension, make harness, new harness, custom harness, crear harness. Creates Tau skills, extensions, or harnesses after exploring project context, Tau architecture, and relevant references."
+---
+
+## Activation Contract
+
+Use this workflow when the user asks to **create a new skill, extension, or harness** for Tau.
+
+Tau has three artifact types you can create:
+
+| Artifact | Format | Location | Purpose |
+|----------|--------|----------|---------|
+| **Skill** | `.md` with frontmatter | `.tau/skills/<name>/SKILL.md` or `~/.tau/skills/<name>/SKILL.md` | Markdown instructions the agent loads via `/skill:<name>` |
+| **Extension** | `.py` (extension class) | `.tau/extensions/<name>.py` or `~/.tau/extensions/<name>.py` | Python code with `@tool`, `@command`, `@on` decorators |
+| **Harness** | `.toml` | `.tau/harnesses/<name>.toml` or `~/.tau/harnesses/<name>.toml` | TOML config for personality, tools, approval, subagents |
+
+## Hard Rules
+
+1. **ALWAYS explore before creating** — never jump to implementation without context.
+2. Follow the exploration order: project → Tau architecture → web references.
+3. After exploring, present a plan to the user before writing files.
+4. Reference existing examples when creating new artifacts.
+5. Validate syntax after creation (ruff for .py, tomllib for .toml, frontmatter parse for .md).
+
+## Exploration Phase (MANDATORY)
+
+### Step 1 — Explore the project
+
+Read project context to understand naming, conventions, and existing patterns:
+
+- `AGENTS.md` or project README for guidelines
+- Existing skills (`ls .tau/skills/`, `ls ~/.tau/skills/`)
+- Existing extensions (`ls .tau/extensions/`, `ls ~/.tau/extensions/`, `ls example_extensions/`)
+- Existing harnesses (`ls .tau/harnesses/`, `ls ~/.tau/harnesses/`)
+- `pyproject.toml` for project metadata
+
+### Step 2 — Explore Tau's architecture
+
+Read the relevant source files to understand the API:
+
+**For skills**:
+- `src/tau_coding/skills.py` — Skill dataclass, load/expand/format
+- `src/tau_coding/resources.py` — `parse_markdown_resource()` for frontmatter format
+
+**For extensions**:
+- `src/tau_coding/extensions.py` — Extension base class, @tool/@command/@on decorators
+- `src/tau_coding/tools.py` — `_wrap_tool_with_events()` for event dispatch
+- Existing examples in `example_extensions/`
+
+**For harnesses**:
+- `src/tau_coding/harness.py` — HarnessDefinition, _parse_harness_file()
+- `dev-notes/harnesses.md` — full harness guide
+- Existing examples in `.tau/harnesses/` or `~/.tau/harnesses/`
+
+### Step 3 — Search the web (when relevant)
+
+When the skill, extension, or harness wraps or integrates an external service, search for:
+- API documentation
+- Best practices
+- Python client libraries
+- Security considerations
+
+## Execution Steps
+
+### Creating a Skill
+
+1. Choose a kebab-case name that matches the user-facing trigger.
+2. Create `.tau/skills/<name>/SKILL.md` (project) or `~/.tau/skills/<name>/SKILL.md` (user):
+
+```markdown
+---
+name: <skill-name>
+description: "Trigger: {trigger phrases}. {One-line summary}."
+---
+
+## Activation Contract
+
+When to use this skill...
+
+## Hard Rules
+
+Non-negotiable constraints...
+
+## Execution Steps
+
+1. First step...
+2. Second step...
+
+## Output Contract
+
+What this skill produces.
+```
+
+3. Frontmatter rules:
+   - `name` matches the directory name
+   - `description` is one line with trigger words first
+   - Only simple `key: value` pairs (Tau's parser is minimal)
+4. Verify: create a test invocation with `python -c "from tau_coding.skills import load_skills; skills = load_skills(); assert any(s.name == '<name>' for s in skills)"`
+
+### Creating an Extension
+
+1. Choose a PascalCase class name and a kebab-case file name.
+2. Create `.tau/extensions/<name>.py` (project) or `~/.tau/extensions/<name>.py` (user):
+
+```python
+"""Docstring describing the extension."""
+
+from tau_coding.extensions import Extension, tool, command, on
+
+
+class <Name>Extension(Extension):
+    @tool("<tool_name>", "<Tool description>")
+    def <method_name>(self, <params>) -> <return_type>:
+        \"\"\"Docstring.\"\"\"
+        ...
+
+    @command("<cmd_name>", description="<description>")
+    def <method_name>(self, args: str) -> str | None:
+        ...
+        return ...
+
+    @on("<event_name>")
+    def <method_name>(self, event: dict) -> dict | None:
+        ...
+        return None  # or {"block": True, "reason": "..."}
+```
+
+3. Follow the existing patterns in `example_extensions/hello_ext.py` and `example_extensions/greeting_ext.py`.
+4. Verify: `uv run ruff check .tau/extensions/<name>.py` and test loading with:
+
+```python
+from tau_coding.extensions import ExtensionRegistry
+from pathlib import Path
+reg = ExtensionRegistry()
+reg.add_search_path(Path(".tau/extensions"))
+instances = reg.load_all()
+assert any("<name>" in i.path for i in instances)
+```
+
+### Creating a Harness
+
+1. Choose a short name (one word, kebab-case).
+2. Create `.tau/harnesses/<name>.toml` (project) or `~/.tau/harnesses/<name>.toml` (user):
+
+```toml
+name = "<name>"
+description = "<One-line description>"
+
+[personality]
+system_prompt = "You are..."
+
+[tools]
+builtin = ["read", "write", "edit", "bash"]
+
+[approval]
+default = "allow"
+
+[approval.rules]
+bash = "deny"
+
+[[subagents]]
+name = "<agent-name>"
+instructions = "<agent instructions>"
+tools = ["read"]
+```
+
+3. Supported sections: `name`, `description`, `[personality]` (system_prompt, guidelines), `[provider]` (name, model, thinking), `[tools]` (builtin, extensions), `[approval]` (default, rules), `[[subagents]]` (name, instructions, tools).
+4. Verify: `python -c "from tau_coding.harness import load_harness; h = load_harness('<name>'); print(f'OK: {h.name}')"` and `python -c "import tomllib; tomllib.loads(open('.tau/harnesses/<name>.toml').read()); print('TOML OK')"`
+
+## Output Contract
+
+After completing, report:
+- What was created (skill/extension/harness) and its path
+- Key sections or decorators used
+- Verification results (parsing, loading, syntax checks)
+- How to invoke/use it (`/skill:<name>`, runs automatically, `tau --harness <name>`)

tau_biggz-0.1.3/AGENTS.md

@@ -0,0 +1,81 @@
+# Tau Agent Instructions
+
+Tau is a Python implementation of Pi's minimalist coding-agent harness architecture. The goal is to develop it incrementally, with each phase clearly documented and tested.
+
+## Project Roadmap
+
+The implementation roadmap is tracked in GitHub issue #1:
+
+- https://github.com/alejandro-ao/tau/issues/1
+
+Use that issue as the primary reference for phase ordering and architectural intent.
+
+## Architecture Principles
+
+Preserve Pi's core separation of concerns:
+
+```text
+AgentHarness = reusable agent brain
+AgentSession = coding-agent environment
+TUI = one possible frontend
+```
+
+Tau should be organized around these layers:
+
+```text
+tau_ai      provider/model streaming layer
+tau_agent   portable agent harness, loop, tools, events, sessions
+tau_coding  CLI app, resources, skills, extensions, commands, TUI integration
+```
+
+Keep the core agent package independent of CLI, Textual, Rich rendering, session file locations, and application-specific resource loading.
+
+## TUI Direction
+
+Use Textual for the full interactive TUI, but only behind an adapter boundary. The agent harness should emit events; UI layers should consume those events.
+
+Early phases should prioritize:
+
+1. print-mode CLI
+2. Rich renderers
+3. Textual interactive app
+
+Do not let Textual become a dependency of the reusable agent harness.
+
+## Development Workflow
+
+- Work in small, documented phases.
+- Keep changes aligned with the roadmap issue.
+- Add or update docs when introducing architectural concepts.
+- Add tests for behavior before expanding features.
+- Run tests and Python commands through `uv` (for example, `uv run pytest` or `uv run python ...`) so they use the project environment.
+- Prefer simple, explicit abstractions over framework-heavy designs.
+- Keep commits atomic: one coherent feature, fix, docs update, refactor, or cleanup per commit.
+
+## GitHub Issue and PR Formatting
+
+- When creating or editing GitHub issues and pull requests from the CLI, write multiline Markdown bodies through a temporary file or heredoc and pass them with `--body-file`.
+- Do not pass escaped newlines like `\n` inside quoted `--body` strings; GitHub will render them literally instead of as line breaks.
+- Use Markdown headings, blank lines, bullets, and backticks for commands/paths so issue and PR descriptions are readable.
+- After creating or editing a GitHub issue or PR body, verify the rendered source with `gh issue view ... --json body` or `gh pr view ... --json body` when practical.
+
+## Python Guidelines
+
+- Target the Python version declared in `pyproject.toml`.
+- Prefer typed dataclasses or schema models for core messages, events, tools, and sessions.
+- Keep async boundaries explicit.
+- Use fake providers and fake tools for deterministic agent-loop tests.
+- Avoid provider-specific assumptions in core agent code.
+
+## Documentation Expectations
+
+Each substantial phase should leave behind beginner-friendly notes under `dev-notes/` (build journals, design docs, ADRs), explaining:
+
+- what was added
+- why it exists
+- how it maps to Pi's design
+- how to test or use it
+
+When a phase adds or changes user-facing behavior, also update the published docs
+under `website/src/content/docs/` (the "Use Tau" guides and reference).
+

tau_biggz-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing to Tau
+
+Thanks for helping improve Tau. Tau is both a usable terminal coding agent and a teaching codebase for understanding how coding agents are built. Contributions should preserve that dual purpose: make the tool better while keeping the architecture small, readable, and easy to learn from.
+
+## Project philosophy
+
+Tau is organized around three layers:
+
+```text
+tau_ai      provider/model streaming layer
+tau_agent   portable agent harness, loop, tools, events, sessions
+tau_coding  CLI app, resources, skills, extensions, commands, TUI integration
+```
+
+The key boundary is:
+
+```text
+AgentHarness = reusable agent brain
+AgentSession = coding-agent environment
+TUI = one possible frontend
+```
+
+Please keep these principles in mind:
+
+- **Small layers beat magic.** Each package should have one clear job.
+- **Events are the contract.** The harness emits typed events; UI and renderers consume them.
+- **The core stays portable.** `tau_agent` should not depend on the CLI, Textual, Rich, local config paths, or Tau-specific resource loading.
+- **Tools are ordinary typed functions.** Prefer explicit schemas and structured results.
+- **Sessions are durable and inspectable.** Avoid changes that make history hard to read, resume, or export.
+- **Documentation follows implementation.** User-facing behavior and architectural decisions should be documented.
+
+## Local development
+
+Use `uv` for Python commands so they run in the project environment.
+
+```bash
+uv sync --dev
+uv run tau --version
+```
+
+Run Tau from the checkout:
+
+```bash
+uv run tau
+uv run tau -p "explain this repo"
+```
+
+## Checks before submitting
+
+Run the relevant focused tests while developing, then run the full checks before opening a pull request when practical:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+For the documentation site (a [Hugo](https://gohugo.io/) project):
+
+```bash
+cd website
+hugo server -D
+hugo --minify
+```
+
+## Where changes belong
+
+Use the layer boundaries to decide where code should live:
+
+- Provider integrations, model adapters, and provider-neutral streaming belong in `tau_ai`.
+- Agent loop behavior, tool abstractions, events, messages, harnesses, and portable session primitives belong in `tau_agent`.
+- CLI behavior, slash commands, TUI integration, local config, resources, skills, prompt templates, and coding-specific tools belong in `tau_coding`.
+- Textual-specific code should stay behind the TUI layer.
+- Rich rendering should not leak into the reusable agent harness.
+
+If a change crosses layers, prefer adding a small typed boundary instead of importing app-specific details into core code.
+
+## Adding a provider or model
+
+The built-in provider catalog is data, not code: edit
+`src/tau_coding/data/catalog.toml` and open a PR — no Python changes needed.
+Each `[[providers]]` table declares the provider's name, kind
+(`openai-compatible`, `anthropic`, or `openai-codex`), base URL, models,
+default model, context windows, and thinking configuration. Validation happens
+at load time, so a typo fails tests with a pointed error message.
+
+For personal or unreleased providers, create `~/.tau/catalog.toml` with the
+same schema — it is overlaid on the built-in catalog (your values win, models
+are unioned) and needs no PR at all.
+
+## Testing expectations
+
+- Add or update tests for behavior changes.
+- Use fake providers and fake tools for deterministic agent-loop tests.
+- Keep core tests free of provider-specific assumptions.
+- Add regression tests for bugs.
+- Prefer focused tests that describe the behavior being protected.
+
+## Documentation expectations
+
+For substantial architectural or phase-oriented work, add beginner-friendly notes under `dev-notes/` explaining:
+
+- what changed
+- why it exists
+- how it maps to Tau's architecture
+- how to test or use it
+
+For user-facing behavior, update the published docs under:
+
+```text
+website/src/content/docs/
+```
+
+## Release process
+
+Tau is published to PyPI as `tau-ai`. Publishing is a production release action,
+not a side effect of every commit merged to `main`.
+
+To prepare a release, intentionally bump `[project].version` in `pyproject.toml`
+and merge that change through a pull request. The PyPI workflow publishes only
+when it detects that version change, or when a maintainer uses an explicit
+release trigger such as a published GitHub Release or manual workflow dispatch.
+See [dev-notes/release-process.md](dev-notes/release-process.md) for the full
+process.
+
+## Pull request guidelines
+
+Good Tau pull requests are small, focused, and easy to review. Please include:
+
+- the motivation for the change
+- a summary of behavior changes
+- tests or checks you ran
+- screenshots or terminal output for TUI/CLI changes when useful
+- notes about compatibility, migrations, config changes, or provider-specific behavior
+
+Avoid unrelated refactors in feature or bug-fix PRs. If a larger design change is needed, open an issue or discussion first.
+
+## Roadmap alignment
+
+Tau is developed incrementally. For larger changes, check the roadmap issue before starting:
+
+<https://github.com/alejandro-ao/tau/issues/1>
+
+When in doubt, favor the smallest step that preserves the architecture and teaches the design clearly.

tau_biggz-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro AO
+
+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.