Metadata-Version: 2.4
Name: gospelo-kata
Version: 0.3.0
Summary: KATA Markdown™ toolkit for human-AI collaboration: schema, validation, and template in a single file
Project-URL: Repository, https://github.com/gospelo-dev/kata
Author: gospelo
License-Expression: MIT
License-File: LICENSE.md
License-File: LICENSE_ja.md
Keywords: document-generation,excel,html-editor,json-schema,markdown,template
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 :: Documentation
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# gospelo-kata — KATA Markdown™ for Human-AI Collaboration

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/gospelo-dev/kata/blob/main/LICENSE.md)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
[![AI Collaborative](https://img.shields.io/badge/AI-Collaborative-ff6f00.svg?logo=openai&logoColor=white)](#why-gospelo-kata)
[![KATA Markdown](https://img.shields.io/badge/Format-KATA_Markdown-00bcd4.svg)](#kata-markdown-format)

A document format and toolkit designed for **human-AI collaboration**. KATA Markdown™ embeds schema, data, and template in a single file — readable and actionable by both humans and AI without special instructions.

## Why gospelo-kata?

KATA Markdown™ is designed so that both humans and AI can read, understand, and work with the same document. The format is self-describing: AI can understand the template structure from the embedded schema and prompt without needing external instructions, while humans can read and edit the same file naturally. It acts as a harness for autonomous AI — schema, validation, and trust management guide AI output along safe, structured paths.

When generating documents with AI, you often face these problems:

- **No structure** — AI outputs free-form text that's hard to validate or reuse
- **No round-trip** — once rendered, you can't extract the original data back
- **No validation** — schema violations go unnoticed until review
- **AI needs coaching** — you have to explain the output format every time

gospelo-kata solves this with a **single `.kata.md` file** that contains everything: schema definition, structured data, and a Jinja2-compatible template (built-in engine, no external dependency). The embedded `**Schema**` and `**Prompt**` blocks let AI understand the template on its own — no separate instructions needed. Rendered output preserves data bindings via `data-kata` annotations, enabling round-trip extraction and automated validation.

## Features

- **Human-AI collaborative format** — both humans and AI can read, edit, and generate from the same file
- **Self-describing templates** — embedded `**Schema**` and `**Prompt**` blocks let AI understand the template without external instructions
- **Single-file format** — schema, data, and template in one `.kata.md` file
- **YAML shorthand schemas** — define types concisely (`string!`, `enum(a,b,c)`, `items[]!:`)
- **Round-trip** — extract structured data back from rendered documents
- **Lint** — validate both templates and rendered output (20+ rules)
- **AI-friendly** — `assemble` command lets AI generate only YAML data; the toolkit handles the rest
- **Secure packaging** — KATA ARchive™ (`.katar`) bundles templates with integrity verification and trust management
- **Multi-format output** — Markdown, Excel, and HTML
- **VSCode extension** — real-time lint, hover info, preview CSS
- **Zero external dependencies** for core features (built-in Jinja2 3.1.6-compatible engine; PyYAML required, openpyxl optional for Excel)

## KATA ARchive™ (.katar) — Secure Template Packages

KATA ARchive™ is a secure, single-file template package format. A `.katar` file bundles template, schema, prompt, manifest, and optional images into a ZIP archive that AI can autonomously discover, understand, and use — no manual instructions needed.

- **Self-contained** — everything AI needs is in one file
- **Integrity-verified** — `pack` computes a hash stored in `manifest.json`; tampered packages are rejected on load
- **Sandboxed** — only `manifest.json`, `_tpl.kata.md`, and image files are allowed; all other file types are blocked
- **Trust-managed** — AI prompt execution requires explicit user approval; changes to prompts trigger re-confirmation
- **Structure integrity** — rendered `.kata.md` output embeds a hash to detect post-render tampering of template structure

```bash
# Create, pack, and use a template
gospelo-kata pack-init ./my_template/
gospelo-kata pack ./my_template/ -o my_template.katar
gospelo-kata init --from-package my_template.katar
```

See the [Template Package Guide](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/template-package.md) for details.

## Installation

```bash
pip install gospelo-kata

# With Excel support
pip install gospelo-kata[excel]
```

Requires Python 3.11+.

## Quick Start

### 1. Create a document from scratch

````bash
cat > todo_tpl.kata.md << 'EOF'
**Prompt**

```yaml
This template generates a task checklist.
Describe items in the items array with task and done fields.
```

# {{ title }}

| Task | Done |
|------|:----:|
{% for item in items %}| {{ item.task }} | {{ item.done }} |
{% endfor %}

<details>
<summary>Schema Reference</summary>

**Schema**

```yaml
title: string!
items[]!:
  task: string!
  done: boolean
```

**Data**

```yaml
title: Sprint Tasks
items:
  - task: Set up CI pipeline
    done: true
  - task: Write API tests
    done: false
  - task: Deploy to staging
    done: false
```

</details>
EOF

gospelo-kata render todo_tpl.kata.md -o outputs/todo.kata.md
gospelo-kata lint outputs/todo.kata.md
````

### 2. Use a built-in template

```bash
# List available templates
gospelo-kata templates

# Initialize a project
gospelo-kata init --type checklist -o ./my-project/
```

### 3. AI workflow (recommended)

AI generates only the YAML data; `assemble` combines it with a built-in template:

```bash
# 1. Check schema
gospelo-kata show-schema checklist --format yaml

# 2. AI creates data.yml following the schema

# 3. Assemble template + data
gospelo-kata assemble --type checklist --data data.yml

# 4. Render and validate
gospelo-kata render checklist_tpl.kata.md -o outputs/checklist.kata.md
gospelo-kata lint outputs/checklist.kata.md
```

### 4. Extract data (round-trip)

```bash
gospelo-kata extract outputs/checklist.kata.md -o extracted.json
```

Reconstructs the original structured data from the rendered document.

## KATA Markdown™ Format

A `_tpl.kata.md` file has four blocks:

````markdown
**Prompt**

```yaml
Generate a security checklist with categories and items.
Each item needs an id, status (draft/pending/approve/reject), and tags.
```

# {{ title }}

{% for cat in categories %}
## {{ cat.name }}

| ID | Status | Tags |
|----|--------|------|
{% for item in cat.items %}| {{ item.id }} | {{ item.status }} | {{ item.tags | join(", ") }} |
{% endfor %}
{% endfor %}

<details>
<summary>Schema Reference</summary>

**Schema**

```yaml
title: string!
version: string
categories[]!:
  id: string!
  name: string!
  items[]!:
    id: string!
    status: enum(draft, pending, approve, reject)
    tags: string[]
```

**Data**

```yaml
title: Security Checklist
version: "1.0"
categories:
  - id: auth
    name: Authentication
    items:
      - id: auth-01
        status: draft
        tags: [web, api]
```

</details>
````

### Schema Shorthand

| Notation                   | Meaning                                     |
| -------------------------- | ------------------------------------------- |
| `string`                         | Optional string                             |
| `string!`                        | Required string                             |
| `integer`, `number`, `boolean`   | Typed values                                |
| `int`, `float`, `bool`, `str`    | Aliases (→ integer, number, boolean, string) |
| `enum(a, b, c)`                  | Enumeration                                 |
| `string[]`                       | String array                                |
| `items[]!:`                      | Required array of objects (indent children) |

### Rendered Output

`gospelo-kata render` produces annotated Markdown:

- `<span data-kata="p-{path}">value</span>` — data bindings
- `<div data-kata-each="collection">` — loop markers
- `<details>` section with Schema + Data for reconstruction

## Built-in Templates

| Type        | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| `checklist` | Structured checklist with categories, status tracking, and automation levels |
| `test_spec` | Test case specification with prerequisites and expected results              |
| `agenda`    | Meeting agenda with decisions, action items, and time allocation             |

## CLI Commands

| Command           | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `templates`       | List available templates                                  |
| `init`            | Initialize project from a template                        |
| `render`          | Render a `.kata.md` template to annotated output          |
| `assemble`        | Combine built-in template + data file into `_tpl.kata.md` |
| `lint`            | Validate templates and rendered documents                 |
| `extract`         | Extract structured data from rendered output              |
| `validate`        | Validate JSON/YAML data against a schema                  |
| `generate`        | Generate Markdown/Excel/HTML from JSON data               |
| `pack`            | Pack a template directory into a `.katar` archive         |
| `pack-init`       | Scaffold a new template directory                         |
| `show-schema`     | Display template schema                                   |
| `show-prompt`     | Display AI prompt                                         |
| `fmt`             | Auto-format `data-kata` spans                             |
| `coverage`        | Analyze checklist coverage                                |
| `edit`            | Browser-based data editor                                 |
| `workflow-status` | Track pipeline progress                                   |

See the [CLI Reference](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/cli-reference.md) for full details.

## AI Integration

gospelo-kata is designed to work with AI assistants. The `assemble` command minimizes what AI needs to generate — just YAML data following the schema.

**Supported AI tools:**

- **Claude Code** — skill files in `skill/claude-code/`
- **GitHub Copilot Chat** — instructions via `.github/copilot-instructions.md`

The 3-step workflow (`data.yml` → `assemble` → `render` + `lint`) works reliably even with smaller models that have limited context windows.

## VSCode Extension

Install from [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=gospelo.kata-lint). The `kata-lint` extension provides:

- Real-time lint diagnostics in the Problems panel
- Hover information for `data-kata` attributes
- Preview CSS for kata-specific styles

See the [VSCode Integration Guide](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/vscode-integration.md).

## Documentation

- [Quick Start](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/quick-start.md)
- [CLI Reference](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/cli-reference.md)
- [KATA Markdown™ Format](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/kata-markdown-format.md)
- [Lint Rules](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/lint-rules.md)
- [Workflow Guide](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/workflow-guide.md)
- [VSCode Integration](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/vscode-integration.md)
- [Copilot Setup](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/copilot-setup.md)
- [Template Package](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/template-package.md)
- [Prompt Design Guide](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/prompt-design-guide.md)
- [Type Conversion](https://github.com/gospelo-dev/kata/blob/main/docs/manual/en/type-conversion.md)

## License

MIT — free for commercial use. Documents generated by this software and templates created by users are the intellectual property of their respective creators. When used with AI services, data may be transmitted to AI providers. See [LICENSE.md](https://github.com/gospelo-dev/kata/blob/main/LICENSE.md) for details.
