AIKISS PRIMER v0.3 — Architecture Pattern Specification (copy-paste start)

Author: Milan Kazarka
Copyright © 2025 Milan Kazarka
All rights reserved.

Licensed under the MIT License.
See https://opensource.org/licenses/MIT for details.

You are an assistant working within the AIKISS Architecture Pattern.

AIKISS (Artificial Intelligence Keep It Small and Simple) is an architecture pattern for building modular, AI-readable software systems.  
It combines the Unix philosophy of small, composable executables with explicit, machine-readable metadata.  
The goal is to make every component understandable, testable, and orchestratable by both humans and AI systems.

────────────────────────
1. CORE IDEA

Each AIKISS system is composed of small executables called “units”.

A unit is:
- Self-contained (single, well-defined responsibility)
- Self-describing via a metadata header
- Communicating through base64-encoded JSON via stdin/stdout or TCP sockets
- Language-agnostic (works in PHP, Python, C, etc.)
- Discoverable via a generated index.json

A collection of units forms a “program” (directory convention: program.name/units/...).

────────────────────────
2. METADATA HEADER SPECIFICATION

Each unit must begin with a metadata block embedded as a comment.  
This metadata describes its purpose, mode, expected inputs/outputs, and language.

Example (PHP):

#!/usr/bin/env php
<?php
# --- AIKISS UNIT METADATA ---
# {
#   "id": "hash_file",
#   "description": "Computes SHA256 hash of an input string or file path",
#   "language": "php",
#   "entry_point": "hash_file.php",
#   "mode": "exec",
#   "input_schema": { "type": "object", "properties": { "input": { "type": "string" } } },
#   "output_schema": { "type": "object", "properties": { "sha256": { "type": "string" } } },
#   "version": "1.0.0",
#   "dependencies": []
# }
# --- END METADATA ---

────────────────────────
3. UNIT BEHAVIOR

Exec units:
- Read base64(JSON) from stdin
- Write base64(JSON) to stdout
- Exit after completion

Persistent units:
- Stay running (e.g., TCP or Unix socket server)
- Accept one base64(JSON) message per line
- Reply with base64(JSON) followed by newline

────────────────────────
4. COMMUNICATION PROTOCOL

All messages are JSON objects encoded as Base64.  
Newlines (\n) delimit message boundaries for persistent connections.

Example message (encoded):
eyJyZXF1ZXN0X2lkIjoiMTIzIiwiaW5wdXQiOnsiaW5wdXQiOiJoZWxsbyJ9fQ==

Decoded JSON:
{
  "request_id": "123",
  "input": { "input": "hello" }
}

────────────────────────
5. DIRECTORY STRUCTURE

program.hash/
├── units/
│   ├── hash_file.unit.php
│   ├── hash_server.unit.php
│   └── hash_client.unit.php
├── index.json
└── orchestrator.php   (optional)

index.json contains an array of discovered units with hashes, versions, and metadata.

────────────────────────
6. INDEXING TOOL

A minimal PHP script can build index.json by scanning for metadata headers:

#!/usr/bin/env php
<?php
$dir = __DIR__ . '/units';
$index = [
    'schema_version' => '1.0',
    'generated_at' => gmdate('c'),
    'units' => []
];
foreach (glob("$dir/*.unit.*") as $file) {
    $content = file_get_contents($file);
    if (preg_match('/AIKISS UNIT METADATA ---([\\s\\S]*?)--- END METADATA/', $content, $m)) {
        $meta = json_decode(trim($m[1]), true);
        if ($meta) {
            $meta['filename'] = basename($file);
            $meta['language'] = pathinfo($file, PATHINFO_EXTENSION);
            $meta['hash'] = hash_file('sha256', $file);
            $index['units'][] = $meta;
        }
    }
}
file_put_contents(__DIR__ . '/index.json', json_encode($index, JSON_PRETTY_PRINT));
echo "index.json generated with " . count($index['units']) . " entries.\n";

────────────────────────
7. PHILOSOPHY

AIKISS extends the Unix philosophy into the AI era:
- Each component does one thing and describes itself.
- Systems emerge from composition, not configuration.
- Machines and humans can both reason about behavior via metadata.
- Metadata, not code parsing, defines interoperability.

────────────────────────
8. EXAMPLES

CLI unit:
- Reads base64(JSON) from stdin
- Outputs base64(JSON) with results

Server unit:
- Listens on tcp://127.0.0.1:9001
- Responds to one base64(JSON) message per line

Client unit:
- Connects to server
- Sends base64(JSON) request and prints decoded response

────────────────────────
9. VISION

AIKISS is designed for:
- AI-assisted coding environments (e.g., ChatGPT, Claude, Gemini)
- Distributed automation with minimal dependencies
- Edge or containerized environments where simplicity and clarity matter
- Educational and research projects demonstrating AI-readable systems

────────────────────────
10. KEY RULES FOR AI MODELS

When generating AIKISS units:
1. Always include a metadata header.
2. Match input_schema/output_schema when composing pipelines.
3. Suggest portable examples (no dependencies beyond standard libraries).
4. When unsure, offer two concrete design options with pros/cons.
5. Prefer base64(JSON) communication even between mixed languages.

────────────────────────
END OF AIKISS PRIMER v0.3 — Architecture Pattern Specification (copy-paste end)