cuga-harness-kit 0.1.0__py3-none-any.whl

cuga_harness_kit/cli.py

@@ -0,0 +1,136 @@
+"""`cuga-harness-kit init` — scaffold cuga skill files for Claude Code, Cursor, Codex, and Bob."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from cuga_harness_kit.render import render_agents_section, render_bob, render_mdc
+
+SKILLS_DIR = Path(__file__).parent / "skills"
+ALL_TARGETS = ("claude", "cursor", "codex", "bob")
+AGENTS_START = "<!-- cuga-harness-kit:start -->"
+AGENTS_END = "<!-- cuga-harness-kit:end -->"
+
+
+def _skill_dirs() -> list[Path]:
+    return sorted(p for p in SKILLS_DIR.iterdir() if (p / "SKILL.md").is_file())
+
+
+def _detect_cuga_message(cwd: Path) -> str:
+    pyproject = cwd / "pyproject.toml"
+    looks_like_cuga_checkout = (cwd / "src" / "cuga").is_dir() or (
+        pyproject.is_file() and 'name = "cuga"' in pyproject.read_text(errors="ignore")
+    )
+    if looks_like_cuga_checkout:
+        return "Detected an existing cuga source checkout — skills will reference your local `cuga` package."
+    return "No existing cuga installation detected — skills will guide you through `pip install cuga` from scratch."
+
+
+def _write_file(path: Path, content: str, *, force: bool, dry_run: bool, written: list[str], skipped: list[str]) -> None:
+    if path.exists():
+        if path.read_text() == content:
+            skipped.append(f"{path} (already up to date)")
+            return
+        if not force:
+            skipped.append(f"{path} (exists, differs — pass --force to overwrite)")
+            return
+    if dry_run:
+        written.append(f"{path} (dry-run)")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    written.append(str(path))
+
+
+def _write_agents_md(cwd: Path, skill_paths: list[Path], *, dry_run: bool, written: list[str], skipped: list[str]) -> None:
+    block_body = "\n".join(render_agents_section(p) for p in skill_paths)
+    block = f"{AGENTS_START}\n\n{block_body}{AGENTS_END}\n"
+
+    path = cwd / "AGENTS.md"
+    if path.exists():
+        existing = path.read_text()
+        if AGENTS_START in existing and AGENTS_END in existing:
+            pre, _, rest = existing.partition(AGENTS_START)
+            _, _, post = rest.partition(AGENTS_END)
+            new_content = f"{pre}{block}{post}"
+        else:
+            new_content = existing.rstrip("\n") + "\n\n" + block
+    else:
+        new_content = block
+
+    if path.exists() and path.read_text() == new_content:
+        skipped.append(f"{path} (already up to date)")
+        return
+    if dry_run:
+        written.append(f"{path} (dry-run)")
+        return
+    path.write_text(new_content)
+    written.append(str(path))
+
+
+def init(targets: list[str], *, force: bool, dry_run: bool, cwd: Path | None = None) -> None:
+    cwd = cwd or Path.cwd()
+    skill_paths = _skill_dirs()
+    written: list[str] = []
+    skipped: list[str] = []
+
+    print(_detect_cuga_message(cwd))
+
+    if "claude" in targets:
+        for skill_path in skill_paths:
+            src = skill_path / "SKILL.md"
+            dest = cwd / ".claude" / "skills" / skill_path.name / "SKILL.md"
+            _write_file(dest, src.read_text(), force=force, dry_run=dry_run, written=written, skipped=skipped)
+
+    if "cursor" in targets:
+        for skill_path in skill_paths:
+            src = skill_path / "SKILL.md"
+            dest = cwd / ".cursor" / "rules" / f"cuga-{skill_path.name}.mdc"
+            _write_file(dest, render_mdc(src), force=force, dry_run=dry_run, written=written, skipped=skipped)
+
+    if "codex" in targets:
+        _write_agents_md(cwd, [p / "SKILL.md" for p in skill_paths], dry_run=dry_run, written=written, skipped=skipped)
+
+    if "bob" in targets:
+        for skill_path in skill_paths:
+            src = skill_path / "SKILL.md"
+            dest = cwd / ".bob" / "rules" / f"cuga-{skill_path.name}.md"
+            _write_file(dest, render_bob(src), force=force, dry_run=dry_run, written=written, skipped=skipped)
+
+    print(f"\n{len(written)} file(s) written, {len(skipped)} skipped.")
+    for line in written:
+        print(f"  wrote:    {line}")
+    for line in skipped:
+        print(f"  skipped:  {line}")
+    print(
+        '\nNext step: open this folder in Claude Code, Cursor, Codex, or Bob, and try asking '
+        '"help me build a cuga tool" or "how do I launch cuga".'
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="cuga-harness-kit")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="scaffold cuga skill files into the current directory")
+    init_parser.add_argument(
+        "--targets",
+        default=",".join(ALL_TARGETS),
+        help=f"comma-separated subset of {ALL_TARGETS} (default: all)",
+    )
+    init_parser.add_argument("--force", action="store_true", help="overwrite files that already exist and differ")
+    init_parser.add_argument("--dry-run", action="store_true", help="print what would be written, write nothing")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        targets = [t.strip() for t in args.targets.split(",") if t.strip()]
+        unknown = set(targets) - set(ALL_TARGETS)
+        if unknown:
+            parser.error(f"unknown target(s): {', '.join(sorted(unknown))} (choose from {ALL_TARGETS})")
+        init(targets, force=args.force, dry_run=args.dry_run)
+
+
+if __name__ == "__main__":
+    main()

cuga_harness_kit/render.py

@@ -0,0 +1,57 @@
+"""Render a canonical Claude SKILL.md into Cursor .mdc, a Codex AGENTS.md section, or a Bob rules file.
+
+Claude, Cursor, Codex, and Bob each read assistant guidance in a different
+shape (per-skill directory + frontmatter / single rule file + frontmatter /
+one shared file with no frontmatter / a rules directory with no frontmatter
+and no selective loading). Rather than hand-maintaining four copies of the
+same content, every skill is authored once as SKILL.md and the other shapes
+are derived from it here, at scaffold time.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+_FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n(.*)", re.DOTALL)
+_HEADING_RE = re.compile(r"^(#{1,5})(\s)", re.MULTILINE)
+
+
+def parse_skill_md(skill_md_path: Path) -> tuple[dict, str]:
+    """Split a SKILL.md file into (frontmatter dict, body markdown)."""
+    text = skill_md_path.read_text()
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        raise ValueError(f"{skill_md_path} has no YAML frontmatter")
+    frontmatter = yaml.safe_load(match.group(1)) or {}
+    body = match.group(2).strip("\n")
+    return frontmatter, body
+
+
+def render_mdc(skill_md_path: Path) -> str:
+    """SKILL.md -> Cursor .mdc content: same description, alwaysApply: false, body verbatim."""
+    frontmatter, body = parse_skill_md(skill_md_path)
+    header = yaml.safe_dump(
+        {"description": frontmatter["description"], "alwaysApply": False},
+        sort_keys=False,
+        allow_unicode=True,
+    ).strip()
+    return f"---\n{header}\n---\n\n{body}\n"
+
+
+def render_agents_section(skill_md_path: Path) -> str:
+    """SKILL.md -> one '## <name>' section for AGENTS.md, headings demoted one level."""
+    frontmatter, body = parse_skill_md(skill_md_path)
+    demoted = _HEADING_RE.sub(r"#\1\2", body)
+    return f"## {frontmatter['name']}\n\n_{frontmatter['description']}_\n\n{demoted}\n"
+
+
+def render_bob(skill_md_path: Path) -> str:
+    """SKILL.md -> a Bob rules file: plain markdown, no frontmatter (Bob doesn't support it
+    or selective loading — every file under .bob/rules/ is injected into every conversation
+    in full), body verbatim.
+    """
+    _, body = parse_skill_md(skill_md_path)
+    return f"{body}\n"

cuga_harness_kit/skills/author-policy/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: cuga-author-policy
+description: Use when the user wants to govern agent behavior with a cuga policy - block/redirect an intent, add step-by-step playbook guidance, require approval before a tool runs, enhance a tool's description, or reshape agent output format.
+---
+
+# Authoring a cuga policy
+
+A cuga **policy** is a rule the runtime enforces on a `CugaAgent`, unlike a runtime *skill* (`cuga-build-cuga-skill`) which the agent optionally chooses to load. There are 5 policy types.
+
+## Step 1 — identify which type
+
+| The user wants to... | Type |
+|---|---|
+| Block or redirect a specific kind of request | `intent_guard` |
+| Give the agent step-by-step guidance for a workflow | `playbook` |
+| Require human approval before a tool runs | `tool_approval` |
+| Add usage guidance/examples to a tool's description | `tool_guide` |
+| Reshape the agent's response into JSON/table/markdown/etc. | `output_formatter` |
+
+## Step 2 — pick programmatic SDK or markdown file
+
+**Programmatic (recommended for code you already control):** attach at agent construction time via `agent.policies`:
+
+```python
+await agent.policies.add_intent_guard(
+    name="Block Delete Operations",
+    description="Prevents deletion of critical data",
+    keywords=["delete", "remove", "erase"],
+    response="Deletion operations are not permitted for security reasons.",
+    priority=100,  # higher = checked first
+)
+
+await agent.policies.add_playbook(
+    name="Budget Analysis Workflow",
+    description="Multi-step process for analyzing financial budgets",
+    natural_language_trigger=["When user asks to analyze their budget"],
+    content="# Budget Analysis Workflow\n\n## Step 1: ...",
+    priority=50,
+)
+```
+
+**Markdown file (for the `manager` web UI, or policies you want checked into a project):** save a file with YAML frontmatter + markdown body to the matching `.cuga/` subfolder, then restart or re-publish so it's picked up:
+
+| Type | Save to |
+|---|---|
+| `playbook` | `.cuga/playbooks/playbook_<name>.md` |
+| `intent_guard` | `.cuga/guards/guard_<name>.md` |
+| `tool_guide` | `.cuga/guides/guide_<name>.md` |
+| `tool_approval` | `.cuga/approvals/approval_<name>.md` |
+| `output_formatter` | `.cuga/formatters/formatter_<name>.md` |
+
+Shared frontmatter fields across all 5 types: `id`, `name`, `description`, `enabled`, `priority`, `type`, `triggers` (shape varies by type — see below).
+
+## Mode: Playbook
+
+```yaml
+---
+description: Brief description of what this playbook does
+enabled: true
+id: playbook_<unique_id>
+name: <Playbook Name>
+priority: 50
+triggers:
+  natural_language:
+  - keyword 1
+  - keyword phrase
+  target: intent
+  threshold: 0.5
+type: playbook
+---
+# <Title>
+## Overview
+## Parameters
+- **parameter_name** (required/optional): description
+## Steps
+### 1. <Step Name> — constraints: MUST / SHOULD / MAY
+## Examples
+## Troubleshooting
+## Best Practices
+```
+
+## Mode: Intent Guard
+
+```yaml
+---
+description: Description of what intents this guard blocks
+enabled: true
+id: guard_<unique_id>
+name: <Guard Name>
+priority: 90        # 90-100 recommended: guards should win priority ties
+triggers:
+  natural_language:
+  - blocked intent 1
+  target: intent
+  threshold: 0.7     # strict matching for guards
+type: intent_guard
+intent_examples:
+- 5+ example phrases of the blocked intent, for matching
+response:
+  response_type: natural_language   # natural_language | json | template
+  content: |
+    Custom message explaining why this is blocked + alternatives.
+allow_override: false   # true = user can bypass, false = enforced
+---
+```
+
+## Mode: Tool Guide
+
+```yaml
+---
+description: Enhanced guidance for specific tools
+enabled: true
+id: guide_<unique_id>
+name: <Guide Name>
+priority: 50
+triggers:
+  tool_match:
+  - tool_name_1
+  target: tools
+type: tool_guide
+target_tools: [tool_name_1, tool_name_2]   # or target_apps: [app_name] for all tools in an app
+guide_content: |
+  ## When to Use / Best Practices / Common Pitfalls / Parameter Guidelines / Examples / Related Tools
+prepend: false   # true = insert before the tool's own description, false = after
+---
+```
+
+## Mode: Tool Approval
+
+```yaml
+---
+description: Require approval for sensitive operations
+enabled: true
+id: approval_<unique_id>
+name: <Approval Policy Name>
+priority: 100   # highest priority recommended
+triggers:
+  tool_match: [sensitive_tool_1]
+  target: tools
+type: tool_approval
+required_tools: [sensitive_tool_1]     # or required_apps: [app_name]
+approval_message: |
+  Explain why approval is required and what will happen.
+show_code_preview: true
+auto_approve_after: null   # null = never auto-approve (recommended); or seconds e.g. 30/60/300
+---
+```
+
+## Mode: Output Formatter
+
+```yaml
+---
+description: Format output in a specific structure
+enabled: true
+id: formatter_<unique_id>
+name: <Formatter Name>
+priority: 50
+triggers:
+  natural_language: [format keyword 1]
+  target: agent_response   # must be agent_response for formatters
+  threshold: 0.6
+type: output_formatter
+format_type: json   # json | markdown | table | csv | custom
+format_config: |
+  {"schema": {"type": "object", "properties": {"field1": {"type": "string"}}, "required": ["field1"]}}
+---
+```
+
+## Testing
+
+```bash
+cuga start competition --local
+```
+
+Trigger the policy with matching keywords/intent and confirm the expected block/guidance/approval/format behavior shows up.
+
+## Reference
+
+Full worked templates: `docs/starterkit/.cursor/{intent_guard,playbook,tool_guide,tool_approval,output_formatter}.md` in the cuga-agent repo. Policy data models: `src/cuga/backend/cuga_graph/policy/models.py`. SDK docs: https://docs.cuga.dev/docs/sdk/policies/

cuga_harness_kit/skills/build-agent/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: cuga-build-agent
+description: Use when the user wants to write Python code that creates or invokes a CugaAgent or CugaSupervisor, e.g. "build an agent with cuga", "how do I call agent.invoke", "set up a multi-agent supervisor".
+---
+
+# Building with the CugaAgent SDK
+
+## Single agent
+
+```python
+from cuga import CugaAgent
+from langchain_core.tools import tool
+import asyncio
+
+@tool
+def add_numbers(a: int, b: int) -> int:
+    """Add two numbers together"""
+    return a + b
+
+agent = CugaAgent(tools=[add_numbers])
+
+async def main():
+    result = await agent.invoke("What is 5 + 3?")
+    print(result.answer)
+
+asyncio.run(main())
+```
+
+Key points:
+- Tools are plain LangChain `@tool`-decorated functions (or an OpenAPI/MCP provider — see `cuga-build-tool`).
+- `await agent.invoke(message, thread_id=...)` — `thread_id` isolates conversation state per user/session; omit it for a one-off call.
+- `agent.stream()` gives real-time execution events instead of a single final result.
+- `agent.policies` is the entry point for attaching Intent Guard / Playbook / Tool Approval / Tool Guide / Output Formatter policies programmatically — see `cuga-author-policy`.
+- Knowledge/RAG is on by default (`enable_knowledge=True`) — see `cuga-knowledge-rag`; pass `enable_knowledge=False` to turn it off.
+- The underlying LangGraph graph is reachable for advanced use cases (custom nodes, inspecting state) if the simple API isn't enough.
+
+## Multi-agent (CugaSupervisor)
+
+```python
+from cuga import CugaAgent, CugaSupervisor
+from langchain_core.tools import tool
+import asyncio
+
+@tool
+def get_customers(limit: int = 10) -> str:
+    """Fetch top customers from CRM."""
+    return "Alice ($250k); Bob ($180k)"
+
+@tool
+def send_email(to: str, body: str) -> str:
+    """Send an email."""
+    return f"Email sent to {to}"
+
+async def main():
+    crm_agent = CugaAgent(tools=[get_customers])
+    crm_agent.description = "CRM and customer data"
+
+    email_agent = CugaAgent(tools=[send_email])
+    email_agent.description = "Sending emails and notifications"
+
+    supervisor = CugaSupervisor(agents={"crm": crm_agent, "email": email_agent})
+    result = await supervisor.invoke("Get our top customer and email them a thank-you")
+    print(result.answer)
+
+asyncio.run(main())
+```
+
+- Each sub-agent needs a `.description` — the supervisor uses it to decide who handles what.
+- Mix local `CugaAgent`s with remote agents via A2A: pass an `"agent_name": {"type": "external", "description": "...", "config": {"a2a_protocol": {...}}}` entry in `agents=`.
+- Pass data between sub-agents with `variables=["var_name"]`.
+- `CugaSupervisor.from_yaml("path/to/config.yaml")` loads agents from a config file instead of constructing them in code.
+- Try it live first: `cuga start demo_supervisor` (see `cuga-install-and-launch`).
+
+## Reference
+
+Full SDK docs: https://docs.cuga.dev/docs/sdk/cuga_agent/ and https://docs.cuga.dev/docs/sdk/cuga_supervisor

cuga_harness_kit/skills/build-cuga-skill/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: cuga-build-cuga-skill
+description: Use when the user wants a running CugaAgent to load a new capability at runtime via cuga's own skill system, e.g. "add a skill to my agent", "create a .cuga/skills SKILL.md", "how does load_skill work".
+---
+
+# Authoring a cuga runtime skill
+
+This is different from the IDE-assistant skill you're reading right now. **cuga's own agents** can discover and load `SKILL.md` files at runtime via a `load_skill` tool — this skill teaches you how to author one of those.
+
+## Where skills live
+
+Controlled by `[skills] root` in `settings.toml` (or `DYNACONF_SKILLS__ROOT`):
+
+| `root` value | Directory | Notes |
+|---|---|---|
+| `cuga` (default) | `.cuga/skills/` | cuga's own convention, avoids colliding with `.agents/skills/` written by other tools |
+| `agents` | `.agents/skills/` | shared convention used by e.g. `npx skills` |
+| `global_agents` | `~/.config/agents/skills/` | global, not project-scoped |
+| `global_cuga` | `~/.config/cuga/skills/` | legacy global path |
+
+Skills are discovered recursively (`**/SKILL.md`) under whichever root is active.
+
+## SKILL.md shape (cuga runtime contract)
+
+Required frontmatter: **`name`** and **`description`** (shown to the agent in its available-skills list — write a description the agent can use to decide when to load it). Optional **`requirements`**: a pip/npm package or list of packages the skill needs installed. Everything below the frontmatter is arbitrary markdown — the full instruction text handed back by `load_skill` when the agent loads this skill.
+
+```markdown
+---
+name: my-skill
+description: Use when the user asks to <do X>. Loads instructions for <Y>.
+requirements: some-pip-package
+---
+
+# My Skill
+
+Step-by-step instructions, code snippets, examples — whatever the agent
+needs in its context to actually perform the task.
+```
+
+Name validation: no path separators or `..` in `name` — cuga sanitizes/rejects unsafe or Jinja2-template-injected values in `name`/`description` for prompt-injection safety.
+
+## Try it
+
+```bash
+cuga start demo_skills
+```
+
+Runs with `[advanced_features] sandbox_mode = "native"` by default. For sandboxed execution instead: `uv sync --extra opensandbox` then use the `opensandbox` mode, or `uv sync --group sandbox` + `cuga start demo --sandbox` with `[skills]` enabled for Docker/Podman isolation.
+
+## Installing a ready-made skill
+
+Anthropic publishes ready-made skill folders (e.g. `pptx`) that follow the same `SKILL.md` convention:
+
+```bash
+npx skills add https://github.com/anthropics/skills --skill pptx -a universal
+```
+
+This drops it under `.agents/skills/pptx/SKILL.md`. To use cuga's default layout instead, copy/symlink it into `.cuga/skills/`. Add `-g` to install globally. Restart `cuga start demo_skills` (or your app) afterward so skills are rescanned — there's no hot-reload.
+
+## Don't confuse this with policies
+
+A runtime skill is instructional content the agent chooses to load. A policy (playbook, intent guard, etc. — see `cuga-author-policy`) is a rule the runtime *enforces* on the agent regardless of whether it "chooses" to. Use a skill for optional know-how, a policy for a constraint or workflow that must always apply.

cuga_harness_kit/skills/build-tool/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: cuga-build-tool
+description: Use when the user wants to give a cuga agent a new capability via a Python function, REST/OpenAPI service, or MCP server, e.g. "add a tool", "connect this API to cuga", "register an MCP server".
+---
+
+# Registering tools with cuga
+
+cuga supports three tool integration types:
+
+| Type | Best for | Configured via | Loading |
+|---|---|---|---|
+| **LangChain** | Python functions, rapid prototyping | direct import, pass to `CugaAgent(tools=[...])` | Runtime |
+| **OpenAPI** | REST APIs, existing services | `mcp_servers.yaml` | Build-time |
+| **MCP** | Custom protocols, complex integrations | `mcp_servers.yaml` | Build-time |
+
+## LangChain tool (fastest path)
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def lookup_order(order_id: str) -> str:
+    """Look up an order by ID and return its status."""
+    ...
+
+agent = CugaAgent(tools=[lookup_order])
+```
+
+This is a runtime-loaded tool: no config file, no restart needed, just pass it into the `CugaAgent` constructor. Write a clear docstring — it becomes the tool description the agent's reasoning engine sees.
+
+## OpenAPI / MCP (registry-based)
+
+For REST APIs or MCP servers, add an entry to `mcp_servers.yaml` (path: `src/cuga/backend/tools_env/registry/config/mcp_servers.yaml` in a cuga-agent checkout). These are build-time: the tool registry (`cuga start registry`, or bundled into any `demo_*`/`manager` service) loads this config at startup, so changes need a restart to take effect.
+
+See the registry's own README for the exact config schema and worked examples: `src/cuga/backend/tools_env/registry/README.md`, plus `docs/examples/cuga_with_runtime_tools/README.md` for a full walkthrough combining different tool types with MCP.
+
+## Which to reach for
+
+- One-off Python function, prototyping, or logic that lives in your app already → LangChain tool.
+- An existing REST API you don't want to hand-wrap → OpenAPI entry in `mcp_servers.yaml`.
+- A third-party or custom MCP server → MCP entry in `mcp_servers.yaml`.
+
+## Enhancing how the agent uses a tool
+
+Once a tool exists, you can shape *how* the agent uses it without touching its code — that's a `tool_guide` or `tool_approval` policy (require confirmation before a sensitive tool runs, or append extra usage guidance/examples to its description). See `cuga-author-policy`.

cuga_harness_kit/skills/debug-trajectory/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: cuga-debug-trajectory
+description: Use when a cuga agent run misbehaved (wrong tool called, silently blocked, wrong output format) and the user wants to inspect what actually happened.
+---
+
+# Debugging a cuga agent run
+
+## Trajectory viewer
+
+Every run is logged to a trajectory data directory (`<cuga log dir>/trajectory_data`). Inspect it visually:
+
+```bash
+cuga viz
+```
+
+Launches a web dashboard for browsing execution trajectories: what the reasoning engine decided at each step, which tools it called with what arguments, and what came back. Start here before reading raw logs — it's usually faster to spot the wrong branch/tool call visually than to grep JSON.
+
+## Environment sanity check
+
+```bash
+cuga doctor
+```
+
+Run this first if the agent won't even start, or behaves inconsistently across environments — it validates the environment/dependency setup.
+
+## `cuga status`
+
+```bash
+cuga status <service|all>
+```
+
+Confirms whether the service you expect to be running actually is, before chasing a bug that's really just "nothing is listening on that port."
+
+## Common failure patterns
+
+- **Tool "not found" or never called** — check the tool actually got passed to `CugaAgent(tools=[...])`, or (for OpenAPI/MCP tools) that the registry service (`cuga start registry`, or the registry bundled in a `demo_*`/`manager` service) picked up your `mcp_servers.yaml` change — those are build-time, not hot-reloaded.
+- **Request silently redirected/blocked with no obvious reason** — an `intent_guard` policy may be matching. Check `.cuga/guards/` (or policies added via `agent.policies.add_intent_guard`) for a guard whose `triggers`/`intent_examples` overlap the query, and check `priority` — guards default to high priority (90-100) and are checked before other policies. See `cuga-author-policy`.
+- **Response in the wrong shape** — an `output_formatter` policy may be firing (or not firing when expected) based on its `triggers.natural_language` keywords and `threshold`. Lower/raise the threshold or adjust keywords.
+- **Tool paused waiting on nothing** — a `tool_approval` policy is likely gating that tool; check `.cuga/approvals/` for `required_tools`/`required_apps` matches and `auto_approve_after`.
+- **`thread_id` confusion** — state (conversation history, session-scoped knowledge) is isolated per `thread_id`. If a run seems to have "forgotten" something from a previous call, confirm the same `thread_id` was passed both times.
+- **Multi-agent: wrong sub-agent picked** — the `CugaSupervisor` routes based on each sub-agent's `.description`. Vague or overlapping descriptions between sub-agents cause misrouting — make them distinct and specific.
+
+## Policy-level test coverage
+
+If you're debugging policy interaction bugs specifically, the policy engine's own integration tests are a good reference for expected behavior: `src/cuga/backend/cuga_graph/policy/tests/` in a cuga-agent checkout (covers intent guard blocking/priority resolution, playbook guidance injection, and more).

cuga_harness_kit/skills/getting-started/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: cuga-getting-started
+description: Use when the user wants to install, launch, or build something with the cuga agent framework (pip package `cuga`), or asks "how do I use cuga" / "how do I build an agent with cuga" — routes to the right cuga-harness-kit skill instead of guessing.
+---
+
+# Getting started with cuga
+
+cuga (`pip install cuga`, [github.com/cuga-project/cuga-agent](https://github.com/cuga-project/cuga-agent)) is an agent orchestration framework: a reasoning engine + pluggable tools (OpenAPI/MCP/LangChain) + a policy system + optional RAG knowledge base + multi-agent supervision, built on LangGraph.
+
+This skill is the entry point. Read the description of the skill that matches what the user is doing before improvising:
+
+| User is trying to... | Use skill |
+|---|---|
+| Install cuga or start the demo UI | `cuga-install-and-launch` |
+| Write Python code that creates/invokes a `CugaAgent` or `CugaSupervisor` | `cuga-build-agent` |
+| Author a new **runtime** skill the agent itself can load (`.cuga/skills/<name>/SKILL.md`) | `cuga-build-cuga-skill` |
+| Register a Python function, OpenAPI spec, or MCP server as a callable tool | `cuga-build-tool` |
+| Add a policy: block an intent, add a playbook, require approval, enhance a tool description, or reshape output | `cuga-author-policy` |
+| Ingest/search documents (RAG) | `cuga-knowledge-rag` |
+| An agent run misbehaved and you need to inspect why | `cuga-debug-trajectory` |
+
+## Two different meanings of "skill"
+
+Don't conflate these — they are unrelated mechanisms that happen to share the `SKILL.md` filename convention:
+
+1. **This skill** (and its siblings) is an *IDE-assistant* skill — it teaches you, the coding assistant, how to work with cuga.
+2. **cuga's own runtime skills** (`.cuga/skills/<name>/SKILL.md`) are loaded by a running `CugaAgent` via a `load_skill` tool, and are what the *agent itself* can call at runtime. See `cuga-build-cuga-skill` when the user wants one of these.
+
+## Ground truth over memory
+
+cuga's CLI and SDK surface can change between versions. If something in these skills looks stale (a flag, a command, a class name), verify against the installed package before trusting the skill text: `python -c "import cuga; print(cuga.__file__)"`, `cuga --help`, or the repo at `src/cuga/` if working inside a checkout.

cuga_harness_kit/skills/install-and-launch/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: cuga-install-and-launch
+description: Use when the user wants to install cuga, start the demo/web UI, or asks what `cuga start` does or which service/mode to run.
+---
+
+# Installing and launching cuga
+
+## Install
+
+```bash
+pip install cuga
+```
+
+(`cuga` requires Python >= 3.10, < 3.14.) For working inside a checkout of the [cuga-agent](https://github.com/cuga-project/cuga-agent) repo itself instead of the published package:
+
+```bash
+git clone https://github.com/cuga-project/cuga-agent.git
+cd cuga-agent
+uv venv --python=3.12 && source .venv/bin/activate
+uv sync
+```
+
+Set an LLM API key before starting anything, e.g. `echo "OPENAI_API_KEY=..." > .env`.
+
+## Launch
+
+```bash
+cuga start <service>
+```
+
+Valid `<service>` values: `demo`, `demo_skills`, `demo_crm`, `demo_docs`, `demo_health`, `demo_knowledge`, `demo_supervisor`, `travel_agent`, `manager`, `registry`, `appworld`.
+
+- `demo` / `demo_crm` / `demo_supervisor` / `demo_knowledge` / `demo_docs` — launch the chat web UI at `https://localhost:7860` plus a tool registry service on port 8001, each preset wiring up different sample tools (CRM+email, multi-agent supervisor, RAG knowledge, docs) so you can try the matching capability immediately.
+- `demo_skills` — same UI, with cuga's own runtime skill-loading enabled (see `cuga-build-cuga-skill`).
+- `manager` — a draft/publish UI: edit agent config (tools, MCP servers, LLM, policies) as a draft, try it, then publish a versioned config for production chat.
+- `registry` — just the tool registry service (OpenAPI/MCP config), no chat UI.
+- `appworld` / `travel_agent` — specific benchmark/example scenarios.
+
+Other useful commands:
+- `cuga stop <service>` — stop a running service.
+- `cuga status` — show what's currently running.
+- `cuga doctor` — environment/dependency sanity check.
+- `cuga viz` — trajectory viewer dashboard (see `cuga-debug-trajectory`).
+
+There is no `cuga policy` or `cuga knowledge` CLI subcommand — policies and knowledge are managed through the Python SDK (`agent.policies.*`, `agent.knowledge.*`, see `cuga-author-policy` / `cuga-knowledge-rag`) or through the `manager` web UI.
+
+## Next step
+
+Once the UI is up, point the user at `cuga-build-agent` for writing their own Python code against the SDK, or have them just chat with the demo agent directly in the browser.

cuga_harness_kit/skills/knowledge-rag/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: cuga-knowledge-rag
+description: Use when the user wants a cuga agent to ingest, search, or answer questions from documents (PDF/DOCX/XLSX/PPTX/HTML/Markdown/images) - RAG / knowledge base features.
+---
+
+# Knowledge base (RAG)
+
+cuga has a built-in knowledge base: local vector store + **Docling** for parsing/normalizing documents before chunking and embedding, so ingestion stays self-contained with no external document service.
+
+Knowledge is **enabled by default** (`enable_knowledge=True`); the SDK auto-injects knowledge tools/awareness so the agent knows what's available and how to search it.
+
+## Try it
+
+```bash
+cuga start demo_knowledge
+```
+
+Full walkthrough with sample docs: `docs/examples/knowledge_demo/` in a cuga-agent checkout.
+
+## Programmatic use
+
+```python
+from cuga import CugaAgent
+import asyncio
+
+agent = CugaAgent(enable_knowledge=True)
+
+async def main():
+    await agent.knowledge.ingest("/path/to/quarterly_report.pdf")
+
+    result = await agent.invoke("What does the report say about Q4 revenue?")
+    print(result.answer)  # agent searches the knowledge base automatically
+
+    results = await agent.knowledge.search("Q4 revenue figures")
+    for r in results:
+        print(f"{r['filename']} (page {r['page']}): {r['text'][:100]}")
+
+    docs = await agent.knowledge.list_documents()
+    await agent.aclose()
+
+asyncio.run(main())
+```
+
+## Scoping
+
+```python
+# Session-scoped: temporary, tied to one conversation thread
+await agent.knowledge.ingest("/path/to/file.pdf", scope="session", thread_id="user-session-123")
+results = await agent.knowledge.search("query", scope="session", thread_id="user-session-123")
+
+# Agent-scoped (default): permanent, shared across conversations
+await agent.knowledge.ingest("/path/to/file.pdf", scope="agent")
+```
+
+Use `session` scope for per-conversation uploads that shouldn't leak between users; use `agent` scope for a shared reference corpus.
+
+## Disabling
+
+```python
+agent = CugaAgent(tools=[my_tools], enable_knowledge=False)
+```
+
+## Supported types & tuning
+
+PDF, DOCX, XLSX, PPTX, HTML, Markdown, images, and more (via Docling). Embedding provider (`fastembed` default/local, `huggingface`, `openai`, `ollama`, `openrouter`) plus model/batch/concurrency are set under `[knowledge.embeddings]` in `settings.toml` or via `--embeddings-*` CLI flags. Switching provider/model invalidates existing vectors (different dimensionality) — the manage UI (`cuga start manager`) surfaces a "re-index recommended" banner when that happens.
+
+Full provider matrix: https://docs.cuga.dev/docs/sdk/knowledge/

cuga_harness_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: cuga-harness-kit
+Version: 0.1.0
+Summary: Scaffolds Claude Code / Cursor / Codex skills that teach coding agents to build with the cuga framework
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# cuga-harness-kit
+
+Skills that teach Claude Code, Cursor, Codex, and Bob how to install, launch, and build with [cuga](https://github.com/cuga-project/cuga-agent) — the open-source generalist agent framework.
+
+No git clone, no marketplace install. Just:
+
+```bash
+pip install cuga-harness-kit
+cuga-harness-kit init
+```
+
+Run `init` from an empty new project you're starting from scratch, or from inside an existing cuga checkout — either way it writes the same skill set into the current directory:
+
+- `.claude/skills/<name>/SKILL.md` — auto-discovered by Claude Code just by opening the folder.
+- `.cursor/rules/cuga-<name>.mdc` — auto-discovered by Cursor.
+- `AGENTS.md` — read wholesale by Codex (and other `AGENTS.md`-aware tools). Re-running `init` only touches the `<!-- cuga-harness-kit:start/end -->` block, so it won't clobber anything else you've written in that file.
+- `.bob/rules/cuga-<name>.md` — loaded by IBM Bob. Unlike the other three, Bob has no frontmatter/description-based selection: every file under `.bob/rules/` is injected into *every* conversation in full, not just when relevant. (Bob also auto-loads `AGENTS.md` by default, so the Codex output above already reaches it too — the `.bob/rules/` files exist for teams that want per-skill files instead of one shared doc.)
+
+Then open the folder in your assistant of choice and ask something like *"help me build a cuga tool"* or *"how do I launch cuga"*.
+
+## What's included (v1)
+
+| Skill | Teaches |
+|---|---|
+| `getting-started` | Entry point — routes to the right skill below. |
+| `install-and-launch` | `pip install cuga`, `cuga start <mode>`. |
+| `build-agent` | `CugaAgent` / `CugaSupervisor` SDK basics. |
+| `build-cuga-skill` | Authoring cuga's own **runtime** skills (`.cuga/skills/<name>/SKILL.md`) — not to be confused with the IDE-assistant skills in this repo. |
+| `build-tool` | Registering a LangChain / OpenAPI / MCP tool. |
+| `author-policy` | Intent guards, playbooks, tool approval/guides, output formatters — one unified skill. |
+| `knowledge-rag` | Document ingestion/search. |
+| `debug-trajectory` | `cuga viz`, `cuga doctor`, common failure patterns. |
+
+All 8 are authored once, as Claude-native `SKILL.md` files under `src/cuga_harness_kit/skills/`, and rendered into the Cursor/Codex/Bob shapes at `init` time (`src/cuga_harness_kit/render.py`) — there's a single source of truth per skill, not four copies to keep in sync by hand.
+
+## CLI
+
+```bash
+cuga-harness-kit init [--targets claude,cursor,codex,bob] [--force] [--dry-run]
+```
+
+- `--targets` — comma-separated subset of `claude`, `cursor`, `codex`, `bob` (default: all four).
+- `--force` — overwrite `.claude/skills/*`, `.cursor/rules/*`, and `.bob/rules/*` files that already exist with different content (default: skip and report). `AGENTS.md`'s managed block always updates regardless, since it never touches content outside its markers.
+- `--dry-run` — print what would be written without touching disk.
+
+## Development
+
+```bash
+uv sync  # or: pip install -e '.[dev]' equivalent via [dependency-groups]
+uv run pytest
+```
+
+## Phase 2 (not yet built)
+
+Real Claude Code plugin packaging (`.claude-plugin/plugin.json` + marketplace listing for `/plugin install`), slash commands, session hooks, a smarter `update`/diff command, and additional harness targets (Windsurf, `.clinerules`, `GEMINI.md`) — add these only if a real gap shows up.

cuga_harness_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+cuga_harness_kit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuga_harness_kit/cli.py,sha256=UFs9uYiqh-B2T8kDx2kMA5RuJGLZgACYURaQyVs2ykY,5383
+cuga_harness_kit/render.py,sha256=3rSfH0Ap2zTnnSHmjVrnnRhlBJjp69lWudKD6wtYZ5U,2245
+cuga_harness_kit/skills/author-policy/SKILL.md,sha256=AbvTAKFJx9NHQcIiPFYb1ClGHO72hvNYAxPahYPYKxA,5611
+cuga_harness_kit/skills/build-agent/SKILL.md,sha256=ksgfqKq9Wi6hsWlI0AyTqkAeYdobd-1gxMLCg-KAPBI,2934
+cuga_harness_kit/skills/build-cuga-skill/SKILL.md,sha256=La407XvaHT5Za2X8byqfTXDKZN5DWtkJMTGK1wCiPiE,3194
+cuga_harness_kit/skills/build-tool/SKILL.md,sha256=2NXSXAM7W245iIiwNPWI2e1Ok80U6umG_38cMj6aNrs,2347
+cuga_harness_kit/skills/debug-trajectory/SKILL.md,sha256=wezKnjFOErlrBFPg48z-PCGo40k-8TmwicN3bCbAxYg,3029
+cuga_harness_kit/skills/getting-started/SKILL.md,sha256=kG_BBmiL104yhph5wVA2DLsVOSC-iiIudh4DIcGPnQI,2334
+cuga_harness_kit/skills/install-and-launch/SKILL.md,sha256=AOdRV9TqeGL4LyqpcUs-xiFPuDrM_yZPJtdl1AztuF4,2336
+cuga_harness_kit/skills/knowledge-rag/SKILL.md,sha256=qwHzem5uHrvOyQGxNCb5EFq0jZrj6RcutEm2PZXU_zo,2570
+cuga_harness_kit-0.1.0.dist-info/METADATA,sha256=amjmjOV1wH0alg_1lHrh_qns_pXShUeZdg8SWxX0Hpc,3742
+cuga_harness_kit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cuga_harness_kit-0.1.0.dist-info/entry_points.txt,sha256=-yB8fCX2mOnZtj-LotP_YIDlIoy8vbXO-9ywg3n6jGk,63
+cuga_harness_kit-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cuga_harness_kit-0.1.0.dist-info/RECORD,,

cuga_harness_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cuga_harness_kit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cuga-harness-kit = cuga_harness_kit.cli:main

cuga_harness_kit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.