ulkan 0.1.0__tar.gz

ulkan-0.1.0/.agent/docs/ULKAN_MANUAL.md

@@ -0,0 +1,75 @@
+# 📘 Ulkan Operator's Manual
+
+**Welcome, Agent.**
+You are operating within an **Ulkan-scaffolded environment**. This manual is your "Driver's License" for this system. It explains the tools, commands, and structures available to you.
+
+---
+
+## 🚀 1. The Command Line Interface (CLI)
+
+You have access to the `ulkan` CLI. Use it to maintain the project and your own context.
+
+### Core Commands
+
+| Command | Usage | When to use |
+| :--- | :--- | :--- |
+| **`ulkan search`** | `ulkan search <query>` | Search the **Skyll API** for Skills, Workflows, or Tools to add to your project. Supports sorting (`--sort installs`). |
+| **`ulkan list`** | `ulkan list <type>` | View what assets are currently installed in your `.agent/` directory. Use `ulkan list all` to see everything. |
+| **`ulkan add`** | `ulkan add <type> <name>` | Install an asset from the registry (API or local). E.g., `ulkan add skill react-best-practices`. |
+| **`ulkan sync`** | `ulkan sync` | **ALWAYS** after creating or modifying a Skill, Rule, or Workflow. This updates `AGENTS.md` automatically. |
+| **`ulkan build`** | `ulkan build` | When you need to re-analyze the project context and update the "Tech Stack" section of `AGENTS.md`. |
+| **`ulkan adapt`** | `ulkan adapt --[agent]` | If you lose your configuration files. Restores symlinks for specific agents (e.g., `ulkan adapt --claude`). |
+| **`ulkan migrate`** | `ulkan migrate` | If you find legacy configuration folders (like `.claude/` or `.gemini/`) that need to be unified into `.agent/`. |
+
+---
+
+## 📂 2. The `.agent/` Directory
+
+This is your "brain". All your instructions and capabilities are stored here.
+
+```
+.agent/
+├── skills/           # YOUR CAPABILITIES. specialized tasks you can perform.
+│   ├── skill-creator/
+│   ├── adr-creator/
+│   └── ...
+├── workflows/        # YOUR PROCEDURES. Step-by-step guides for complex tasks.
+│   ├── feat.md       # usage: /feat
+│   ├── fix.md        # usage: /fix
+│   └── ...
+├── rules/            # YOUR CONSTRAINTS. "Always-on" policies.
+├── docs/             # PROJECT MEMORY.
+│   ├── product/      # Vision, Architecture
+│   ├── specs/        # Feature Specifications
+│   └── decisions/    # Architecture Decision Records (ADRs)
+└── tools/            # YOUR HANDS. Scripts and utilities.
+    └── scripts/      # Python scripts you can run (e.g., sync_agents_docs.py)
+```
+
+---
+
+## 🛠️ 3. How to Use Your Skills
+
+You don't just "write code". You use **Skills** to perform high-value actions.
+*   **Need to create a new feature?** -> Check `workflows/feat.md`.
+*   **Need to document a decision?** -> Read `skills/adr-creator/SKILL.md` and follow it.
+*   **Need to create a new tool?** -> Read `skills/tools-creator/SKILL.md`.
+
+**💡 Pro Tip**: If you are asked to do something complex, **first check if there is a Skill or Workflow for it**. providing a standardized output is better than guessing.
+
+---
+
+## 🔄 4. Self-Correction & Maintenance
+
+### "I created a new Skill but it's not in AGENTS.md!"
+> Run `ulkan sync`. This script parses the `.agent/skills` directory and updates the table in `AGENTS.md`.
+
+### "I found a bug in a workflow."
+> You are allowed to improve the system! Edit the relevant `.md` file in `.agent/workflows/` and run `ulkan sync`.
+
+### "The project architecture has changed."
+> Update `.agent/docs/product/ARCHITECTURE.md`. Keep the documentation alive.
+
+---
+
+*End of Manual.*

ulkan-0.1.0/.agent/docs/decisions/README.md

@@ -0,0 +1,4 @@
+# Decisions (ADRs)
+Architecture Decision Records (ADRs) for significant storage decisions.
+
+👉 **To record a decision:** Use the `adr-creator` skill.

ulkan-0.1.0/.agent/docs/guidelines/README.md

@@ -0,0 +1,4 @@
+# Guidelines
+Coding standards, naming conventions, and best practices.
+
+👉 **To add a new guideline:** Use the `guidelines-creator` skill.

ulkan-0.1.0/.agent/docs/product/ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# Architecture Overview: Ulkan
+
+## 1. High-Level Design
+
+Ulkan operates on a "Hub and Spoke" model:
+*   **Hub**: The `.agent/` directory (Single Source of Truth).
+*   **Spokes**: The adapter files (e.g., `.claude/`, `copilot-instructions.md`) used by specific tools.
+*   **Engine**: The `ulkan` CLI which manages the synchronization between Hub and Spokes.
+
+## 2. Tech Stack
+
+| Component | Technology | Rationale |
+| :--- | :--- | :--- |
+| **Language** | Python 3.12+ | Modern, typed, compliant with latest standards. |
+| **CLI Framework** | `typer` | Type-hint based CLI creation, robust and easy to maintain. |
+| **Terminal UI** | `rich` | Beautiful, readable output is critical for developer tools. |
+| **Interactivity** | `inquirerpy` | robust interactive prompts for `init` and selection flows. |
+| **Packaging** | `hatchling` | Modern standards-based build backend. |
+
+## 3. Project Structure
+
+```
+src/ulkan/
+├── main.py          # Entry point
+├── commands.py      # CLI command definitions (init, build, adapt, sync)
+├── agents.py        # Logic for specific AI agent adapters
+├── generator.py     # Scaffolding logic (creating .agent structure)
+├── migrator.py      # Logic for ingesting existing agent configs
+├── syncer.py        # Documentation synchronization logic
+├── builder.py       # "AI Build" logic (LLM interaction)
+└── templates/       # Jinja2 templates for artifacts
+```
+
+## 4. Core Concepts
+
+### 4.1. Single Source of Truth (SSOT)
+The `.agent/` folder contains canonical data:
+*   `skills/`: Reusable capabilities (e.g., "Create React Component").
+*   `workflows/`: Standard operating procedures (e.g., "Bug Fix Workflow").
+*   `rules/`: Active constraints.
+*   `docs/`: Product context.
+
+### 4.2. Adaptation
+The `adapt` command creates symbolic links or generated files mapping the SSOT to vendor-specific formats.
+*   *Example*: `.agent` -> `.claude` (Symlink) allows Claude CLI to see the standard structure as its own context.
+
+### 4.3. Synchronization
+The `sync` command ensures `AGENTS.md` (the human/agent readable index) reflects the actual state of the `.agent/` directory.
+
+## 5. Data Flow
+
+1.  **User** runs `ulkan init`.
+2.  **Generator** creates `.agent/` structure.
+3.  **User** runs `ulkan adapt --claude`.
+4.  **Adapter** symlinks `.agent` to `.claude`.
+5.  **User** runs `ulkan build`.
+6.  **Builder** invokes the AI Agent to read project code and populate `AGENTS.md` context sections.

ulkan-0.1.0/.agent/docs/product/README.md

@@ -0,0 +1,4 @@
+# Product Docs
+High-level product documentation like Vision and Architecture.
+
+👉 **To create/reset docs:** Use the `product-docs-creator` skill.

ulkan-0.1.0/.agent/docs/product/VISION.md

@@ -0,0 +1,26 @@
+# Product Vision: Ulkan
+
+## 1. Mission Statement
+To make "agent-ready" the default state for every software project, eliminating the friction between human developers and AI assistants.
+
+## 2. The Problem
+*   **Fragmentation**: Every developer configures their AI agent differently (system prompts, recommended extensions, ignored files).
+*   **Context Loss**: AI agents often lack the "big picture" (architecture, conventions, business goals) leading to hallucinations or misaligned code.
+*   **Maintenance Burden**: Keeping `CLAUDE.md`, `.cursorrules`, and custom instructions in sync is manual and error-prone.
+
+## 3. The Solution: Ulkan
+Ulkan is an **Agentic Scaffolding Tool** that provides a standardized, agent-agnostic interface for any codebase.
+
+*   **Standardized Context**: A strictly defined `.agent/` directory structure acting as the Single Source of Truth (SSOT).
+*   **Universal Compatibility**: Adapters that automatically generate configuration for specific agents (Claude, Gemini, Copilot, etc.) from the SSOT.
+*   **Living Documentation**: CLI tools (`ulkan sync`, `ulkan build`) that keep documentation fresh and accurate.
+
+## 4. Target Audience
+*   **Software Engineers** adapting to AI-assisted workflows.
+*   **Tech Leads** wanting to enforce consistency across team members' AI agents.
+*   **maintainers** of open-source projects who want to make their code base easily understandable by AI contributors.
+
+## 5. Core Values
+*   **Zero Magic**: Everything is explicit files and folders.
+*   **Agent Agnostic**: Don't lock into one specific AI vendor.
+*   **Automated Maintenance**: If it can be scripted, it shouldn't be a wiki page.

ulkan-0.1.0/.agent/docs/specs/README.md

@@ -0,0 +1,4 @@
+# Specs
+Feature specifications and technical requirements.
+
+👉 **To add a new spec:** Use the `specs-creator` skill.

ulkan-0.1.0/.agent/rules/README.md

@@ -0,0 +1,4 @@
+# Rules
+Always-on constraints: code style, security policies, conventions.
+
+👉 **To add a new rule:** Use the `rules-creator` skill.

ulkan-0.1.0/.agent/skills/README.md

@@ -0,0 +1,4 @@
+# Skills
+Modular capabilities loaded on demand. Each skill should have its own folder with a `SKILL.md`.
+
+👉 **To add a new skill:** Use the `skill-creator` skill.

ulkan-0.1.0/.agent/skills/adr-creator/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: adr-creator
+description: >
+  Creates updated Architecture Decision Records (ADRs).
+  Trigger: When user asks to document a decision, change component, or record architectural choice.
+license: Apache-2.0
+metadata:
+  author: ulkan
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "Creating new ADR"
+trigger: "Record decision"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+## When to Create an ADR
+
+Create an ADR when:
+- A significant architectural decision is made.
+- A new technology or pattern is introduced.
+- A decision has non-trivial trade-offs.
+- A previous decision is superseded or deprecated.
+
+## ADR Location
+
+ADRs are located in `.agent/docs/decisions/`.
+Format: `{number}-{kebab-case-title}.md` (e.g., `001-use-postgres.md`).
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for ADR-TEMPLATE.md (Michael Nygard format).

ulkan-0.1.0/.agent/skills/adr-creator/assets/ADR-TEMPLATE.md

@@ -0,0 +1,49 @@
+---
+status: {proposed | accepted | rejected | deprecated | superseded}
+date: {YYYY-MM-DD}
+deciders: {list of people involved}
+---
+
+# {Title}
+
+## Context and Problem Statement
+
+{Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.}
+
+## Decision Drivers
+
+* {driver 1, e.g., a force, facing concern, …}
+* {driver 2, e.g., a force, facing concern, …}
+
+## Considered Options
+
+* {option 1}
+* {option 2}
+* {option 3}
+
+## Decision Outcome
+
+Chosen option: "{option 1}", because {justification}.
+
+### Positive Consequences
+
+* {positive consequence 1}
+* {positive consequence 2}
+
+### Negative Consequences
+
+* {negative consequence 1}
+* {negative consequence 2}
+
+## Pros and Cons of the Options
+
+### {option 1}
+
+* Good, because {argument a}
+* Good, because {argument b}
+* Bad, because {argument c}
+
+### {option 2}
+
+* Good, because {argument a}
+* Bad, because {argument b}

ulkan-0.1.0/.agent/skills/guidelines-creator/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: guidelines-creator
+description: >
+  Creates strict guidelines or best practices documentation.
+  Trigger: When user asks to document coding standards, naming conventions, or recommended workflows.
+license: Apache-2.0
+metadata:
+  author: ulkan
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "Creating guidelines"
+trigger: "Define standard"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+## When to Create Guidelines
+
+Create a guideline when:
+- Establishing a coding standard (e.g., Python style, React hooks usage).
+- Defining a workflow (e.g., Git commit messages, PR process).
+- Documenting best practices that are encouraged but not strictly enforced by linter.
+
+## Guidelines Location
+
+Guidelines are located in `.agent/docs/guidelines/`.
+Format: `{topic-kebab-case}.md` (e.g., `python-style-guide.md`).
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for GUIDELINE-TEMPLATE.md

ulkan-0.1.0/.agent/skills/guidelines-creator/assets/GUIDELINE-TEMPLATE.md

@@ -0,0 +1,22 @@
+# {Guideline Title}
+
+## Context
+{Why is this guideline necessary? What goal does it support?}
+
+## The Guideline
+{Clear description of the practice or standard.}
+
+## Examples
+
+### ✅ Do This
+```{language}
+{Correct example}
+```
+
+### ❌ Don't Do This
+```{language}
+{Incorrect example}
+```
+
+## Exceptions
+{When does this guideline NOT apply?}

ulkan-0.1.0/.agent/skills/product-docs-creator/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: product-docs-creator
+description: >
+  Creates key product documentation (Vision, Architecture) using standard templates.
+  Trigger: When user asks to create, reset, or initialize product vision or architecture docs.
+license: Apache-2.0
+metadata:
+  author: ulkan
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "Creating product docs"
+trigger: "Vision/Architecture"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+## When to Create Product Docs
+
+Use this skill when:
+- Starting a new project or module.
+- The `VISION.md` or `ARCHITECTURE.md` files are missing.
+- You want to reset these documents to a standard structure.
+
+## Document Types & Locations
+
+| Type | File | Description |
+|------|------|-------------|
+| **Vision** | `.agent/docs/product/VISION.md` | Product goals, target audience, needs. |
+| **Architecture** | `.agent/docs/product/ARCHITECTURE.md` | High-level system design, C4 context, stack. |
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for VISION-TEMPLATE.md and ARCHITECTURE-TEMPLATE.md

ulkan-0.1.0/.agent/skills/product-docs-creator/assets/ARCHITECTURE-TEMPLATE.md

@@ -0,0 +1,20 @@
+# System Architecture
+
+## Overview
+{High-level description of the system}
+
+## Component Diagram (C4 Context)
+```mermaid
+graph TD
+    User -->|Uses| System
+    System -->|Queries| Database
+```
+
+## Tech Stack
+- **Frontend**: {React, Vue, etc.}
+- **Backend**: {Python, Node, etc.}
+- **Database**: {Postgres, Mongo, etc.}
+- **Infra**: {Docker, K8s, AWS}
+
+## Key Patterns
+- {Event Sourcing, CQRS, MVC, etc.}

ulkan-0.1.0/.agent/skills/product-docs-creator/assets/VISION-TEMPLATE.md

@@ -0,0 +1,16 @@
+# Product Vision
+
+## Vision Statement
+{Concise, aspiring statement of the future state}
+
+## Target Group
+{Who are the users and customers?}
+
+## Needs
+{What problem does the product solve? What benefit does it provide?}
+
+## Product
+{What product is it? What are the key features?}
+
+## Business Goals
+{How will the product benefit the company? Revenue, growth, etc.}

ulkan-0.1.0/.agent/skills/rules-creator/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: rules-creator
+description: >
+  Creates new AI agent rules to enforce system constraints.
+  Trigger: When user asks to define a new constraint, policy, convention, or "always-on" rule.
+license: Apache-2.0
+metadata:
+  author: ulkan
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "Creating new rules"
+trigger: "Add a rule"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+## When to Create a Rule
+
+Create a rule when:
+- A pattern must be enforced across the entire project (or specific scopes)
+- Security policies need to be explicitly documented for agents
+- Code style conventions are strict and not just "best practices"
+- There are "always-on" constraints that agents must never violate
+
+**Don't create a rule when:**
+- It's a suggestion or guideline (use `docs/guidelines/` instead)
+- It's a temporary constraint
+- It's specific to a single file (add a comment instead)
+
+---
+
+## Rule Structure
+
+```
+.agent/rules/{rule-name}.md
+```
+
+Rules are flat markdown files in `.agent/rules/`.
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for RULE-TEMPLATE.md

ulkan-0.1.0/.agent/skills/rules-creator/assets/RULE-TEMPLATE.md

@@ -0,0 +1,39 @@
+---
+name: {rule-name}
+description: {Short description of the rule}
+trigger: {When this rule applies e.g. "Always", "On Python files"}
+scope: {Glob pattern e.g. "**/*.py", "src/legacy/**"}
+priority: {High/Medium/Low}
+---
+
+## The Rule
+
+{Clear, imperative statement of what rules must be followed or what actions are forbidden.}
+
+## Why
+
+{Brief explanation of the reasoning behind this rule.}
+
+## Valid Examples
+
+### ✅ Do This
+
+```{language}
+{code example}
+```
+
+## Invalid Examples
+
+### ❌ Don't Do This
+
+```{language}
+{code example}
+```
+
+## Exceptions
+
+{List any exceptions to this rule, or "None".}
+
+## Enforcement
+
+{How this rule is enforced or verified.}

ulkan-0.1.0/.agent/skills/skill-creator/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: skill-creator
+description: >
+  Creates new AI agent skills following the Agent Skills spec.
+  Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI.
+license: Apache-2.0
+metadata:
+  author: ulkan
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "Creating new skills"
+trigger: "Create/Add a skill"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## When to Create a Skill
+
+Create a skill when:
+- A pattern is used repeatedly and AI needs guidance
+- Project-specific conventions differ from generic best practices
+- Complex workflows need step-by-step instructions
+- Decision trees help AI choose the right approach
+
+**Don't create a skill when:**
+- Documentation already exists (create a reference instead)
+- Pattern is trivial or self-explanatory
+- It's a one-off task
+
+---
+
+## Skill Structure
+
+```
+skills/{skill-name}/
+├── SKILL.md              # Required - main skill file
+├── assets/               # Optional - templates, schemas, examples
+│   ├── template.py
+│   └── schema.json
+└── references/           # Optional - links to local docs
+    └── docs.md           # Points to docs/developer-guide/*.mdx
+```
+
+---
+
+## Naming Conventions
+
+| Type | Pattern | Examples |
+|------|---------|----------|
+| Generic skill | `{technology}` | `pytest`, `playwright`, `typescript` |
+| Project-specific | `project-{component}` | `project-api`, `project-ui` |
+| Workflow skill | `{action}-{target}` | `skill-creator`, `jira-task` |
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for SKILL.md template

ulkan-0.1.0/.agent/skills/skill-creator/assets/SKILL-TEMPLATE.md

@@ -0,0 +1,51 @@
+---
+name: {skill-name}
+description: >
+  {Short description of what this skill does}
+  Trigger: {When should this skill be used?}
+trigger: "{Short trigger phrase for AGENTS.md}"
+license: Apache-2.0
+metadata:
+  author: {github-url}
+  agent: {agent-name}
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "{When should this skill be automatically invoked?}"
+allowed-tools: {List, Of, Allowed, Tools, Or, *}
+---
+
+## When to Use
+
+Use this skill when:
+- {Condition 1}
+- {Condition 2}
+
+---
+
+## Critical Patterns
+
+{The MOST important rules - what AI MUST follow}
+
+---
+
+## Code Examples
+
+### Example 1: {Description}
+
+```{language}
+{minimal, focused example}
+```
+
+---
+
+## Commands
+
+```bash
+{command 1}  # {description}
+```
+
+---
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for {description of templates}

ulkan-0.1.0/.agent/skills/specs-creator/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: specs-creator
+description: >
+  Creates new technical specifications and feature requirement documents.
+  Trigger: When user asks to create a new spec, feature doc, or technical requirement.
+license: Apache-2.0
+metadata:
+  author: ulkan
+  version: "1.0"
+  scope: [root]
+  auto_invoke: "Creating new specs"
+trigger: "New feature spec"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+## When to Create a Spec
+
+Create a spec when:
+- Starting a new feature or component.
+- Documenting complex technical requirements.
+- Planning a major refactor or migration.
+- The user requests a "spec" or "design doc".
+
+## Spec Location
+
+Specs are located in `.agent/docs/specs/{feature-name}/`.
+Each spec should be a self-contained markdown file, e.g., `SPEC.md` or `{feature}-v1.md`.
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for SPEC-TEMPLATE.md.

ulkan-0.1.0/.agent/skills/specs-creator/assets/SPEC-TEMPLATE.md

@@ -0,0 +1,33 @@
+---
+feature: {feature-name}
+status: {draft | in-progress | implemented | deprecated}
+last_updated: {YYYY-MM-DD}
+title: {Human Readable Title}
+owner: {Team or Individual}
+priority: {P0 | P1 | P2}
+---
+
+## Background
+
+{Context and problem statement. Why are we building this?}
+
+## Requirements
+
+### Functional
+- {Requirement 1}
+- {Requirement 2}
+
+### Non-Functional
+- {Performance, Security, Reliability}
+
+## API Design
+
+{Endpoints, data models, interfaces}
+
+## UI/UX
+
+{Screenshots, wireframes, or descriptions of user interaction}
+
+## Open Questions
+
+- {Question 1}