gospelo-kata 0.4.0

KATA Markdown™ toolkit for human-AI collaboration: schema, validation, and template in a single file

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

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
• No external templating 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

# 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 for details.

Installation

pip install gospelo-kata

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

Requires Python 3.11+.

Quick Start

1. Create a document from scratch

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

# 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; build combines it with a built-in template:

# 1. Check prompt + schema
gospelo-kata export checklist --part prompt,schema

# 2. AI creates data.yml following the schema

# 3. Validate, build, and lint
gospelo-kata import-data checklist data.yml -q
gospelo-kata build checklist data.yml -o outputs/
gospelo-kata lint outputs/checklist.kata.md

4. Extract data (round-trip)

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:

**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
export	Export template parts (prompt, schema, data, body)
import-data	Validate data.yml against template schema
fmt	Auto-format data-kata spans
coverage	Analyze checklist coverage
edit	Browser-based data editor
workflow-status	Track pipeline progress

See the CLI Reference for full details.

AI Integration

gospelo-kata is designed to work with AI assistants. The build 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. 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.

Documentation

• Quick Start
• CLI Reference
• KATA Markdown™ Format
• Lint Rules
• Skill Guide
• VSCode Integration
• Copilot Setup
• Template Package
• Prompt Design Guide
• Type Conversion

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 for details.