aes-cli 0.2.0__py3-none-any.whl

aes/scaffold/setup.md.jinja

@@ -0,0 +1,244 @@
+{% if domain_config %}
+# Command: /setup
+
+Review and customize .agent/ configuration for your project.
+Your `.agent/` directory was initialized with **{{ domain }}** domain defaults. This command helps you tailor the pre-filled content to your specific project.
+
+## Phase 0: Detect Context
+
+Determine which path to follow:
+- **If source files exist** (src/, lib/, app/, or language-specific code) → **Codebase path**: read code to refine the pre-filled config
+- **If the project is empty** (no source code, only .agent/) → **Interview path**: ask the user what they're building to customize the config
+
+All subsequent phases note both approaches where they differ.
+
+## Phase 1: Understand the Project
+
+**Codebase path:**
+1. Read README.md, package config (pyproject.toml / package.json / go.mod / Cargo.toml)
+2. List top-level directories — identify: source code, tests, config, scripts, docs
+3. Identify framework and key dependencies
+4. Note entry point(s) and build system
+
+**Interview path:**
+1. Ask: "What are you building? (1-2 sentences)"
+2. Ask: "What's the tech stack? (language, framework, database, deployment target)"
+3. Based on complexity of answers, optionally ask:
+   - "What are the main operations this system performs?"
+   - "What entities does it manage and what are their lifecycle states?"
+   - "Any security constraints, resource limits, or team conventions?"
+   Stop asking when you have enough to generate useful content.
+
+## Phase 2: Refine Instructions
+
+Edit `.agent/instructions.md` — review and customize the pre-filled content:
+1. **Description**: verify the project purpose matches your actual system
+2. **Quick Reference**: update commands to match your actual scripts and tools
+   - Codebase: extract from package scripts / Makefile / CI config
+   - Interview: confirm with user
+3. **Project Structure**: update directory tree to match reality
+   - Codebase: run directory listing, annotate key dirs
+   - Interview: describe planned structure
+4. **Critical Rules**: add project-specific constraints
+   - Codebase: extract from linter configs, CI checks, README, code comments
+   - Interview: ask about language version, security requirements
+5. **Primary Workflow**: adjust phases to match your actual dev cycle
+6. **Gotchas**: add project-specific hard-won lessons
+   - Codebase: look for workarounds in comments, error-prone patterns
+   - Interview: ask "anything that's bitten you before?"
+
+## Phase 3: Review Skills
+
+Skills have been pre-populated for the **{{ domain }}** domain. For each skill in `skills/`:
+1. Review the `.skill.yaml` manifest — verify inputs, outputs, and triggers match your system
+2. Review the `.md` runbook — customize the decision tree and error handling
+3. Add any missing skills specific to your project
+4. Remove any pre-filled skills that don't apply
+5. Update `skills/ORCHESTRATOR.md` — adjust pipeline order and decision tree
+
+## Phase 4: Review Workflow
+
+{% if domain_config.workflow %}
+A workflow has been pre-populated: `workflows/{{ domain_config.workflow.id }}.yaml`
+1. Review the states — add, remove, or rename to match your actual entity lifecycle
+2. Review transitions — verify the flow matches your process
+3. Update `agent.yaml` if you add/remove workflows
+{% else %}
+No workflow was pre-populated. If your project has entities with lifecycle states:
+1. Identify the primary entity (feature, order, dataset, service, etc.)
+2. Map lifecycle states and transitions
+3. Create `workflows/{id}.yaml`
+4. Update `agent.yaml` workflows list
+{% endif %}
+
+## Phase 5: Review Workflow Commands
+
+Workflow commands define repeating multi-phase workflows the agent executes.
+{% if domain_config.workflow_commands %}
+Pre-populated for the **{{ domain }}** domain:
+{% for cmd in domain_config.workflow_commands %}
+- `{{ cmd.trigger }}` — `.agent/commands/{{ cmd.id }}.md`
+{% endfor %}
+
+For each command:
+1. Review the phases — verify they match your actual workflow
+2. Customize phase content with project-specific scripts, paths, and checks
+3. Add any missing commands, remove any that don't apply
+4. Update `agent.yaml` commands list if you add/remove
+{% else %}
+No workflow commands were pre-populated. Consider adding commands for recurring workflows:
+1. `/build` — project construction
+2. `/run` — execute primary workflow
+3. Create command files in `.agent/commands/`
+4. Register in `agent.yaml` commands list
+{% endif %}
+
+## Phase 6: Review Permissions
+
+Edit `.agent/permissions.yaml`:
+1. Verify **shell read** commands match your inspection tools
+2. Verify **shell execute** commands match your build/test/run tools
+   - Codebase: cross-reference with package scripts, Makefile
+   - Interview: confirm with user
+3. Verify **file write** patterns cover your source directories
+4. Add any project-specific **deny** rules (destructive commands)
+5. Add any **confirm** rules (high-impact commands like deploy, publish)
+6. Update **resource limits** if your project has compute constraints
+
+## Phase 7: Configure Environment
+
+Edit `agent.yaml` environment section:
+- Codebase: scan for `os.environ`, `process.env`, `.env`, `.env.example`
+- Interview: ask "any API keys or config vars needed?"
+List required vars and optional vars with defaults.
+
+## Phase 8: Validate and Sync
+
+```bash
+aes validate
+```
+
+Report: what was customized, any validation errors to fix.
+
+```bash
+aes sync
+```
+
+Re-sync to update tool-specific config files (CLAUDE.md, .cursorrules, etc.) with your changes.
+{% else %}
+# Command: /setup
+
+Populate .agent/ configuration by analyzing the codebase or interviewing the user.
+Run this after `aes init` to replace placeholder content with real project-specific config.
+
+## Phase 0: Detect Context
+
+Determine which path to follow:
+- **If source files exist** (src/, lib/, app/, or language-specific code) → **Codebase path**: read code to extract project knowledge
+- **If the project is empty** (no source code, only .agent/) → **Interview path**: ask the user what they're building
+
+All subsequent phases note both approaches where they differ.
+
+## Phase 1: Understand the Project
+
+**Codebase path:**
+1. Read README.md, package config (pyproject.toml / package.json / go.mod / Cargo.toml)
+2. List top-level directories — identify: source code, tests, config, scripts, docs
+3. Identify framework and key dependencies
+4. Note entry point(s) and build system
+
+**Interview path:**
+1. Ask: "What are you building? (1-2 sentences)"
+2. Ask: "What's the tech stack? (language, framework, database, deployment target)"
+3. Based on complexity of answers, optionally ask:
+   - "What are the main operations this system performs?"
+   - "What entities does it manage and what are their lifecycle states?"
+   - "Any security constraints, resource limits, or team conventions?"
+   Stop asking when you have enough to generate useful content.
+
+## Phase 2: Fill Instructions
+
+Edit `.agent/instructions.md` — replace all `<!-- AGENT: -->` comments:
+1. **Description**: project purpose and primary constraints
+2. **Quick Reference**: 3-5 most common commands
+   - Codebase: extract from package scripts / Makefile / CI config
+   - Interview: ask user or infer from tech stack
+3. **Project Structure**: annotated directory tree
+   - Codebase: run directory listing, annotate key dirs
+   - Interview: describe planned structure
+4. **Critical Rules**: 3-5 inviolable constraints
+   - Codebase: extract from linter configs, CI checks, README, code comments
+   - Interview: ask about language version, security requirements, conventions
+5. **Primary Workflow**: 3-5 phases of the typical dev cycle
+6. **Gotchas**: hard-won lessons
+   - Codebase: look for workarounds in comments, error-prone patterns
+   - Interview: ask "anything that's bitten you before?"
+
+## Phase 3: Define Skills (if skills/ exists)
+
+**Codebase path:** Identify major operations from: CLI commands, API endpoints, scripts/, pipeline stages, scheduled jobs. Each becomes a skill.
+
+**Interview path:** Ask "What are the 2-4 main things this system does?" Each answer becomes a skill.
+
+For each skill:
+1. Create `skills/{id}.skill.yaml` — inputs, outputs, trigger command, error strategy, code location
+2. Create `skills/{id}.md` runbook — purpose, how it works, decision tree, error handling
+3. Update `agent.yaml` skills list
+4. Fill `skills/ORCHESTRATOR.md` — pipeline order, status flow, decision tree
+
+## Phase 4: Define Workflow (if workflows/ exists)
+
+1. Identify the primary entity (feature, order, dataset, service, etc.)
+   - Codebase: look for status columns, enums, state machines
+   - Interview: ask "what's the main thing that moves through your system?"
+2. Map lifecycle states and transitions
+3. Create `workflows/{id}.yaml`
+4. Update `agent.yaml` workflows list
+
+## Phase 5: Define Workflow Commands
+
+Workflow commands define repeating multi-phase workflows the agent executes (e.g. `/build`, `/run`).
+
+If commands exist in `.agent/commands/` (besides `setup.md`):
+1. Review each command's phases — verify they match your actual workflow
+2. Customize phase content with project-specific scripts, paths, and checks
+
+If no workflow commands exist, consider adding:
+1. `/build` — project construction (structure, modules, tests)
+2. `/run` — execute primary workflow end-to-end
+3. Create command files in `.agent/commands/`
+4. Register in `agent.yaml` commands list
+
+## Phase 6: Set Permissions
+
+Edit `.agent/permissions.yaml`:
+1. **Shell read**: inspection commands (git, ls, status)
+2. **Shell execute**: work commands (build, test, run)
+   - Codebase: extract from package scripts, Makefile
+   - Interview: infer from tech stack
+3. **File write**: source directories the agent should modify
+4. **Deny**: destructive commands (rm -rf, DROP, force-push)
+5. **Confirm**: high-impact commands (deploy, publish, push)
+6. **Resource limits**: if the project has compute constraints
+
+## Phase 7: Configure Environment
+
+Edit `agent.yaml` environment section:
+- Codebase: scan for `os.environ`, `process.env`, `.env`, `.env.example`
+- Interview: ask "any API keys or config vars needed?"
+List required vars and optional vars with defaults.
+
+## Phase 8: Validate and Sync
+
+```bash
+aes validate
+```
+
+Report: what was generated, how many skills/states/rules, any validation errors to fix.
+
+```bash
+aes sync
+```
+
+Re-sync to update tool-specific config files (CLAUDE.md, .cursorrules, etc.) with your changes.
+{% endif %}

aes/scaffold/skill.md.jinja

@@ -0,0 +1,27 @@
+# Skill: {{ skill.name }}
+
+## Purpose
+
+{{ skill.runbook_purpose }}
+
+## When to Run
+
+{{ skill.runbook_when }}
+
+## How It Works
+
+{{ skill.runbook_how }}
+
+## Decision Tree
+
+```
+{{ skill.runbook_decision_tree }}
+```
+
+## Error Handling
+
+{{ skill.runbook_error_handling }}
+
+## Code Location
+
+- Primary: `{{ skill.code_primary }}`

aes/scaffold/skill.yaml.jinja

@@ -0,0 +1,175 @@
+{% if skill %}
+# .agent/skills/{{ skill.id }}.skill.yaml
+aes_skill: "1.0"
+
+id: "{{ skill.id }}"
+name: "{{ skill.name }}"
+version: "{{ skill.version }}"
+description: "{{ skill.description }}"
+{% if skill.negative_triggers %}
+negative_triggers:
+{% for nt in skill.negative_triggers %}  - "{{ nt }}"
+{% endfor %}{% endif %}
+{% if skill.activation != "explicit" %}
+activation: "{{ skill.activation }}"
+{% endif %}
+
+stage: {{ skill.stage }}
+phase: "{{ skill.phase }}"
+
+inputs:
+{% if skill.inputs_required %}
+  required:
+{% for inp in skill.inputs_required %}
+    - name: "{{ inp.name }}"
+      type: "{{ inp.type }}"
+      description: "{{ inp.description }}"
+{% endfor %}
+{% else %}
+  required: []
+{% endif %}
+{% if skill.inputs_optional %}
+  optional:
+{% for inp in skill.inputs_optional %}
+    - name: "{{ inp.name }}"
+      type: "{{ inp.type }}"
+{% if inp.default is defined %}
+      default: {{ inp.default }}
+{% endif %}
+      description: "{{ inp.description }}"
+{% endfor %}
+{% else %}
+  optional: []
+{% endif %}
+{% if skill.inputs_environment %}
+  environment:
+{% for env in skill.inputs_environment %}
+    - "{{ env }}"
+{% endfor %}
+{% else %}
+  environment: []
+{% endif %}
+
+{% if skill.outputs %}
+outputs:
+{% for out in skill.outputs %}
+  - name: "{{ out.name }}"
+    type: "{{ out.type }}"
+    description: "{{ out.description }}"
+{% endfor %}
+{% else %}
+outputs: []
+{% endif %}
+
+prerequisites: []
+
+triggers:
+  - type: "manual"
+    command: "{{ skill.trigger_command }}"
+
+error_handling:
+  strategy: "{{ skill.error_strategy }}"
+{% if skill.allowed_tools %}
+
+allowed_tools:
+{% if skill.allowed_tools.shell is defined %}  shell: {{ skill.allowed_tools.shell | lower }}
+{% endif %}{% if skill.allowed_tools.files is defined %}  files:
+{% if skill.allowed_tools.files.read is defined %}{% if skill.allowed_tools.files.read is sameas true or skill.allowed_tools.files.read is sameas false %}    read: {{ skill.allowed_tools.files.read | lower }}
+{% else %}    read:
+{% for p in skill.allowed_tools.files.read %}      - "{{ p }}"
+{% endfor %}{% endif %}{% endif %}{% if skill.allowed_tools.files.write is defined %}{% if skill.allowed_tools.files.write is sameas true or skill.allowed_tools.files.write is sameas false %}    write: {{ skill.allowed_tools.files.write | lower }}
+{% else %}    write:
+{% for p in skill.allowed_tools.files.write %}      - "{{ p }}"
+{% endfor %}{% endif %}{% endif %}{% endif %}{% if skill.allowed_tools.network is defined %}  network: {{ skill.allowed_tools.network | lower }}
+{% endif %}{% if skill.allowed_tools.mcp_servers is defined %}  mcp_servers:
+{% for srv in skill.allowed_tools.mcp_servers %}    - "{{ srv }}"
+{% endfor %}{% endif %}{% endif %}
+
+code:
+  primary: "{{ skill.code_primary }}"
+{% if skill.depends_on %}
+
+depends_on:
+{% for dep in skill.depends_on %}
+  - "{{ dep }}"
+{% endfor %}
+{% endif %}
+{% if skill.blocks %}
+blocks:
+{% for b in skill.blocks %}
+  - "{{ b }}"
+{% endfor %}
+{% endif %}
+
+tags:
+{% for tag in skill.tags %}
+  - "{{ tag }}"
+{% endfor %}
+{% else %}
+# .agent/skills/{{ skill_id }}.skill.yaml
+aes_skill: "1.0"
+
+id: "{{ skill_id }}"
+name: "{{ skill_name }}"
+version: "1.0.0"
+# Description formula: [What it does] + [When to use it] + [Key capabilities]
+# Example: "Discover new datasets from OpenML and Kaggle APIs. Use when the pipeline
+#           needs fresh data or no datasets are in discovered status. Queries multiple
+#           sources, deduplicates, and filters by quality criteria."
+# Keep under 1024 characters. Be specific about triggers and capabilities.
+# <!-- AGENT: Describe what this skill does following the formula above.
+#      If code exists: read the primary source file and summarize its purpose.
+#      If greenfield: ask the user what this operation does. -->
+description: "TODO: describe what this skill does"
+
+# Phrases describing when this skill should NOT be used (optional)
+# negative_triggers:
+#   - "Do NOT use for manual data entry"
+#   - "Do NOT use when API keys are not configured"
+
+# Activation mode: "explicit" (slash command only, default),
+#   "auto" (loaded when description matches), "hybrid" (both)
+# activation: "explicit"
+
+inputs:
+  # <!-- AGENT: Define required and optional inputs for this skill.
+  #      If code exists: look at function signatures, CLI args, config params.
+  #      If greenfield: ask "what does this operation need to run?" -->
+  required: []
+  optional: []
+  environment: []
+
+# <!-- AGENT: Define what this skill produces.
+#      If code exists: look at return values, output files, side effects.
+#      If greenfield: ask "what does this operation produce?" -->
+outputs: []
+
+prerequisites: []
+
+triggers:
+  - type: "manual"
+    # <!-- AGENT: Set the trigger command.
+    #      If code exists: use the actual CLI command or script path.
+    #      If greenfield: infer from tech stack or ask. -->
+    command: "# TODO: add trigger command"
+
+error_handling:
+  strategy: "per-item-isolation"
+
+# Per-skill tool permissions (optional, tool-agnostic format)
+# allowed_tools:
+#   shell: true
+#   files:
+#     read: true
+#     write: ["src/**", "config/**"]
+#   network: true
+#   mcp_servers: ["fetch"]
+
+code:
+  # <!-- AGENT: Set the path to the primary source file for this skill.
+  #      If code exists: identify the main file that implements this operation.
+  #      If greenfield: set to the planned file path. -->
+  primary: "# TODO: path to primary source file"
+
+tags: []
+{% endif %}

aes/scaffold/workflow.yaml.jinja

@@ -0,0 +1,44 @@
+aes_workflow: "1.0"
+
+id: "{{ workflow.id }}"
+entity: "{{ workflow.entity }}"
+description: "{{ workflow.description }}"
+
+states:
+{% for state in workflow.states %}
+  {{ state.id }}:
+    description: "{{ state.description }}"
+{% if state.initial %}
+    initial: true
+{% endif %}
+{% if state.terminal %}
+    terminal: true
+{% endif %}
+{% if state.active %}
+    active: true
+{% endif %}
+{% endfor %}
+
+transitions:
+{% for t in workflow.transitions %}
+  - from: "{{ t.from_state }}"
+    to: "{{ t.to_state }}"
+{% if t.skill %}
+    skill: "{{ t.skill }}"
+{% endif %}
+{% if t.conditions %}
+    conditions:
+{% for c in t.conditions %}
+      - "{{ c }}"
+{% endfor %}
+{% endif %}
+{% if t.on_failure %}
+    on_failure: "{{ t.on_failure }}"
+{% endif %}
+{% if t.description %}
+    description: "{{ t.description }}"
+{% endif %}
+{% endfor %}
+
+idempotency:
+  pattern: "status-gated"

aes/scaffold/workflow_command.md.jinja

@@ -0,0 +1,48 @@
+# Command: {{ cmd.trigger }}
+
+{{ cmd.runbook_purpose }}
+
+## Worker Identity
+
+You are the **{{ cmd.trigger }}** worker — {{ cmd.worker_specialty or cmd.description }}.
+
+## Memory
+
+Before starting, read **all** of `.agent/memory/operations.md`.
+Check the Activity Log for entries since your last **Read Cursor** — these are things other workers did that you haven't seen yet.
+Use this context to inform your work (e.g. what `/build` constructed, what `/run` encountered, decisions made).
+
+After each phase, append a numbered entry to the Activity Log tagged with `{{ cmd.trigger }}`:
+```
+N. [{{ cmd.trigger }}] YYYY-MM-DD: what was done — outcome
+```
+
+When done, update your **Read Cursor** in the Workers table to the last entry number.
+
+## Completion Check
+
+After reading the Activity Log, check if the pipeline is already complete (all items at terminal status and no new items to process). If so:
+
+1. Report the current state summary (counts, statuses, last activity)
+2. Ask the user what to do:
+   - **Re-run**: Clear state and start the pipeline fresh
+   - **New session**: Start a new pipeline with new inputs
+   - **Re-validate**: Re-run validation only on existing artifacts
+   - **Exit**: Nothing to do
+3. Do NOT silently re-execute phases on a finished pipeline
+
+## Phases
+{% for phase in cmd.runbook_phases %}
+
+### {{ loop.index }}. {{ phase.title }}
+
+{{ phase.content }}
+{% endfor %}
+
+## After Completion
+
+1. Update `.agent/memory/operations.md`:
+   - Append final entries to the Activity Log
+   - Update your **Read Cursor** to the last entry number
+   - Add any cross-cutting issues or decisions to the Issues & Decisions section
+2. Report: phases completed, items processed, errors encountered