Mission: This file is the definitive guide for any AI Agent working on this project. It defines the Operating Protocol, Available Skills, and Workflows to ensure consistency and high-quality output.
When you start a task, follow this Search Order:
- Workflows (
.agent/workflows/): Is there a standard procedure for what I'm doing? (e.g., Feature Dev, Bug Fix). - Native Tools: Use
ulkan searchandulkan listto find existing capabilities. - Rules (
.agent/rules/): Are there constraints I must follow? - Skills (
.agent/skills/): Do I have a specific Skill for this? (e.g., creating docs, managing ADRs).
Use the ulkan CLI to maintain the project and your own context.
| Command | Usage | Description |
|---|---|---|
ulkan search |
ulkan search <query> |
Search the Skyll API for Skills, Workflows, or Tools. |
ulkan list |
ulkan list <type> |
View installed assets in .agent/. |
ulkan add |
ulkan add <type> <name> |
Install an asset from the registry. |
ulkan sync |
ulkan sync |
ALWAYS run this after modifying assets to update AGENTS.md. |
ulkan upgrade |
ulkan upgrade |
Check for and install the latest version of Ulkan. |
ulkan uninstall |
ulkan uninstall |
Uninstall Ulkan from the system (supports --dry-run). |
ulkan adapt |
ulkan adapt --[agent] |
Restore configuration for a specific agent. |
Use these skills to perform specialized tasks. Check .agent/skills/ for the full list.
| Skill | Trigger | Description |
|---|---|---|
adr-creator |
"Record decision" | Creates updated Architecture Decision Records (ADRs). Trigger: When user asks to document a dec... |
guidelines-creator |
"Define standard" | Creates strict guidelines or best practices documentation. Trigger: When user asks to document ... |
product-docs-creator |
"Vision/Architecture" | Creates key product documentation (Vision, Architecture) using standard templates. Trigger: Whe... |
rules-creator |
"Add a rule" | Creates new AI agent rules to enforce system constraints. Trigger: When user asks to define a n... |
skill-creator |
"Create/Add a skill" | Creates new AI agent skills following the Agent Skills spec. Trigger: When user asks to create ... |
specs-creator |
"New feature spec" | Creates new technical specifications and feature requirement documents. Trigger: When user asks... |
tools-creator |
"Create a tool/script" | Creates new AI agent tools (scripts, MCP servers, or utilities). Trigger: When user asks to cre... |
workflows-creator |
"Create a workflow" | Creates repeatable workflow documentation. Trigger: When user asks to define a new process, pro... |
Always-on constraints that must be followed. Check .agent/rules/ for details.
| Rule | Trigger | Description |
|---|---|---|
(Run ulkan sync to populate) |
... | ... |
Scripts and utilities available for automation. Check .agent/tools/ for details.
| Tool | Type | Description |
|---|---|---|
lint_agent_setup.py |
Script | The Doctor 🩺 Validates the integrity of the .agent configuration. |
sync_agents_docs.py |
Script | Syncs AGENTS.md with current skills, rules, workflows, and tools. |
Use these workflows to orchestrate complex processes. Trigger with /workflow-name.
| Workflow | Trigger | Goal |
|---|---|---|
/add-to-workflow |
"/add-to-workflow {workflow-names} {instruction}" | Intelligently integrates a new instruction or policy into an existing workflow. |
/build |
"New app/From scratch" | Guide for new product definition (Discovery -> Vision -> Architecture) |
/docs |
"Check docs" | Maintenance workflow to ensure docs consistency |
/feat |
"New feature" | Guide for new features (Spec -> Plan -> Code -> Docs) |
/fix |
"Fix bug" | Protocol for bug fixes (Reproduction -> Fix -> Docs) |
/git-flow |
"Manage branches / Git flow" | Custom Gitflow workflow (Feature -> Dev -> Release -> Main) |
/migrate |
"Migrate project" | Migrate existing agent configs to Ulkan structure |
/refact |
"Code smell/Technical Debt" | Workflow for code refactoring (Test Baseline -> Refactor -> Verify) |
/release |
"Make a release, Release vX.Y.Z, Deploy stable" | Guide for creating stable GitHub releases (Tag -> Changelog -> Release) |
- High-Level: See
.agent/docs/product/ARCHITECTURE.md - Vision: See
.agent/docs/product/VISION.md - Decisions: See
.agent/docs/decisions/
(Agent: Please populate this section during your first analysis)
- Language: Python 3.12+
- Framework: Typer, Rich, InquirerPy
- Database: N/A (Filesystem)
- Infra: GitHub Actions, PyPI
This is a living document.
- Adding a Capability: If you create a new Skill using
skill-creator, add it to the "Core Skills" table above.- Tip: Run
python3 .agent/tools/scripts/sync_agents_docs.pyto auto-update the list!
- Tip: Run
- Adding a Workflow: If you create a new Workflow using
workflows-creator, add it to the "Standard Workflows" table. - Updating Specs: Always update specs in
.agent/docs/specs/when behavior changes.