aes-cli 0.2.0__py3-none-any.whl

aes/scaffold/instructions.md.jinja

@@ -0,0 +1,311 @@
+{% if domain_config and domain_config.instructions_description %}
+# {{ name }} — Agent Instructions
+
+{{ domain_config.instructions_description }}
+
+## Quick Reference
+
+```bash
+{{ domain_config.instructions_quick_ref }}
+```
+
+## Project Structure
+
+```
+{{ domain_config.instructions_project_structure }}
+```
+
+## Critical Rules
+
+{% for rule in domain_config.instructions_rules %}
+{{ loop.index }}. {{ rule }}
+{% endfor %}
+
+## Primary Workflow
+
+{% for phase in domain_config.instructions_workflow_phases %}
+### Phase {{ loop.index }}: {{ phase.title }}
+
+{{ phase.content }}
+
+{% endfor %}
+
+## Key Principle
+
+{{ domain_config.instructions_key_principle }}
+
+## Common Gotchas
+
+{% if domain_config.instructions_gotchas %}
+{% for gotcha in domain_config.instructions_gotchas %}
+- {{ gotcha }}
+{% endfor %}
+{% else %}
+<!-- AGENT: Add project-specific gotchas — hard-won lessons, common mistakes, non-obvious behaviors. -->
+{% endif %}
+
+## AES File Formats
+
+When creating or editing `.agent/` files, follow these formats exactly.
+
+### Skill manifest (`.skill.yaml`)
+
+```yaml
+aes_skill: "1.0"
+
+id: "my-skill"
+name: "My Skill"
+version: "1.0.0"
+description: "What this skill does"
+
+stage: 1
+phase: "processing"
+
+inputs:
+  required:
+    - name: "input_name"
+      type: "string"
+      description: "What this input is"
+  optional:
+    - name: "limit"
+      type: "int"
+      default: 50
+      description: "Max items"
+  environment:
+    - "API_KEY"
+
+outputs:
+  - name: "result"
+    type: "list[str]"
+    description: "What this produces"
+
+triggers:
+  - type: "manual"
+    command: "python scripts/run.py --stage my-skill"
+
+error_handling:
+  strategy: "per-item-isolation"   # or: fail-fast, retry-with-backoff, skip-on-error
+
+code:
+  primary: "pipeline/my_skill.py"
+
+depends_on:
+  - "previous-skill"
+blocks:
+  - "next-skill"
+tags:
+  - "my-tag"
+```
+
+### Workflow (`.yaml`)
+
+```yaml
+aes_workflow: "1.0"
+
+id: "my-workflow"
+entity: "item"
+description: "What this workflow tracks"
+
+states:
+  pending:
+    description: "Awaiting processing"
+    initial: true
+  processed:
+    description: "Successfully processed"
+    terminal: true
+  failed:
+    description: "Processing failed"
+    terminal: true
+
+transitions:
+  - from: "pending"
+    to: "processed"
+    skill: "process"
+    conditions:
+      - "Input is valid"
+  - from: "pending"
+    to: "failed"
+    conditions:
+      - "Processing error"
+
+idempotency:
+  pattern: "status-gated"
+```
+
+Key rules: `aes_skill`/`aes_workflow` version key is **required**. `inputs` is an **object** with `required`/`optional`/`environment` arrays, not a flat list. `states` is an **object** keyed by state ID, not an array. Use `triggers` (array of objects with `type`), not `trigger` (string). Use `error_handling.strategy`, not `error_strategy`. Use `code.primary`, not `code_location`.
+{% else %}
+# {{ name }} — Agent Instructions
+
+<!-- AGENT: Write 1-2 sentences describing what this system does and its primary constraints.
+     If code exists: read README + entry point + package config.
+     If greenfield: ask the user what they're building. -->
+
+## Quick Reference
+
+```bash
+<!-- AGENT: List 3-5 common commands for this project.
+     If code exists: check package.json scripts, Makefile, pyproject.toml, Cargo.toml, go.mod.
+     If greenfield: infer from tech stack ({{ language }}) or ask the user. -->
+```
+
+## Project Structure
+
+```
+<!-- AGENT: Annotate the directory tree with purpose of each key directory.
+     If code exists: run a directory listing and describe what each dir contains.
+     If greenfield: describe the planned structure based on the tech stack. -->
+```
+
+## Critical Rules
+
+<!-- AGENT: List 3-5 inviolable constraints for this project.
+     If code exists: extract from linter config (.eslintrc, ruff.toml, .golangci.yml),
+     CI pipeline (.github/workflows/), README, and code comments.
+     If greenfield: ask about language version, security requirements, conventions.
+     Example: "Python 3.9+ — use `from __future__ import annotations` everywhere." -->
+
+1. **Fail graceful** — Each item wrapped in try/except, log error, continue.
+
+## Domain Model
+
+<!-- AGENT: Describe core entities, their relationships, and primary data flow.
+     If code exists: look for models/, schemas/, types/, database migrations, API routes.
+     If greenfield: ask "What are the main entities and how do they relate?" -->
+
+## Primary Workflow
+
+<!-- AGENT: Define 3-5 phases of the typical development cycle.
+     If code exists: infer from scripts, CI pipeline, and project structure.
+     If greenfield: ask "What's the typical workflow for a task in this project?" -->
+
+### Phase 1: Gather Requirements
+
+<!-- AGENT: What does the agent need to know before starting?
+     If code exists: look at test fixtures, config files, example inputs.
+     If greenfield: ask the user. -->
+
+### Phase 2: Execute
+
+<!-- AGENT: What does the agent do? What commands does it run?
+     If code exists: identify build, run, and test commands.
+     If greenfield: infer from tech stack. -->
+
+### Phase 3: Analyze Results (DO NOT SKIP)
+
+<!-- AGENT: What should the agent check after execution?
+     If code exists: look for test suites, linters, type checkers, CI checks.
+     If greenfield: ask about quality gates. -->
+
+### Phase 4: Iterate
+
+<!-- AGENT: What levers can the agent pull to improve results?
+     If code exists: look for configuration knobs, feature flags, optimization patterns.
+     If greenfield: ask the user. -->
+
+### Phase 5: Deliver
+
+<!-- AGENT: How does the agent deliver the final result?
+     If code exists: look for deploy scripts, publish commands, output directories.
+     If greenfield: ask about delivery mechanism. -->
+
+## Key Principle
+
+The agent's job is NOT just to run commands. It is to understand, analyze, iterate, and deliver quality.
+
+## Common Gotchas
+
+<!-- AGENT: List hard-won lessons and common pitfalls.
+     If code exists: look for workarounds in comments, TODO/FIXME/HACK markers,
+     error-prone patterns, and .env.example for config gotchas.
+     If greenfield: ask "anything that's bitten you before?" -->
+
+## AES File Formats
+
+When creating or editing `.agent/` files, follow these formats exactly.
+
+### Skill manifest (`.skill.yaml`)
+
+```yaml
+aes_skill: "1.0"
+
+id: "my-skill"
+name: "My Skill"
+version: "1.0.0"
+description: "What this skill does"
+
+stage: 1
+phase: "processing"
+
+inputs:
+  required:
+    - name: "input_name"
+      type: "string"
+      description: "What this input is"
+  optional:
+    - name: "limit"
+      type: "int"
+      default: 50
+      description: "Max items"
+  environment:
+    - "API_KEY"
+
+outputs:
+  - name: "result"
+    type: "list[str]"
+    description: "What this produces"
+
+triggers:
+  - type: "manual"
+    command: "python scripts/run.py --stage my-skill"
+
+error_handling:
+  strategy: "per-item-isolation"   # or: fail-fast, retry-with-backoff, skip-on-error
+
+code:
+  primary: "pipeline/my_skill.py"
+
+depends_on:
+  - "previous-skill"
+blocks:
+  - "next-skill"
+tags:
+  - "my-tag"
+```
+
+### Workflow (`.yaml`)
+
+```yaml
+aes_workflow: "1.0"
+
+id: "my-workflow"
+entity: "item"
+description: "What this workflow tracks"
+
+states:
+  pending:
+    description: "Awaiting processing"
+    initial: true
+  processed:
+    description: "Successfully processed"
+    terminal: true
+  failed:
+    description: "Processing failed"
+    terminal: true
+
+transitions:
+  - from: "pending"
+    to: "processed"
+    skill: "process"
+    conditions:
+      - "Input is valid"
+  - from: "pending"
+    to: "failed"
+    conditions:
+      - "Processing error"
+
+idempotency:
+  pattern: "status-gated"
+```
+
+Key rules: `aes_skill`/`aes_workflow` version key is **required**. `inputs` is an **object** with `required`/`optional`/`environment` arrays, not a flat list. `states` is an **object** keyed by state ID, not an array. Use `triggers` (array of objects with `type`), not `trigger` (string). Use `error_handling.strategy`, not `error_strategy`. Use `code.primary`, not `code_location`.
+{% endif %}

aes/scaffold/local.example.yaml.jinja

@@ -0,0 +1,35 @@
+# .agent/local.example.yaml — Template for local overrides
+#
+# Copy this to local.yaml and fill in your values:
+#   cp .agent/local.example.yaml .agent/local.yaml
+#
+# local.yaml is gitignored. It is merged on top of permissions.yaml
+# during `aes sync` so your personal settings apply without modifying
+# shared config files.
+
+permissions:
+  allow:
+    shell:
+      remote: []
+        # Add SSH commands for your remote servers:
+        # - "ssh -i ~/.ssh/my_key user@myhost *"
+
+resources: {}
+  # Adjust resource limits for your machine:
+  # max_cpu_percent: 70
+  # max_memory_percent: 75
+  # notes: "Description of your machine constraints"
+
+environment: {}
+{% if domain_config and domain_config.env_required %}
+  # Required environment variables — set these in local.yaml:
+{% for env in domain_config.env_required %}
+  # {{ env.name }}: ""   # {{ env.description }}
+{% endfor %}
+{% endif %}
+{% if domain_config and domain_config.env_optional %}
+  # Optional environment variables:
+{% for env in domain_config.env_optional %}
+  # {{ env.name }}: "{{ env.default }}"   # {{ env.description }}
+{% endfor %}
+{% endif %}

aes/scaffold/local.yaml.jinja

@@ -0,0 +1,29 @@
+# .agent/local.yaml — Local overrides (NOT committed to git)
+#
+# This file contains project-specific settings that should NOT be shared:
+# SSH keys, server IPs, API key values, resource limits for your machine.
+#
+# Merged on top of permissions.yaml during `aes sync`.
+
+permissions:
+  allow:
+    shell:
+      remote: []
+        # - "ssh -i ~/.ssh/my_key user@myhost *"
+
+resources: {}
+  # max_cpu_percent: 70
+  # max_memory_percent: 75
+  # notes: "Shared VPS — respect other processes"
+
+environment:
+{% if domain_config and domain_config.env_required %}
+{% for env in domain_config.env_required %}
+  # {{ env.name }}: "your-{{ env.name | lower | replace('_', '-') }}-here"
+{% endfor %}
+{% endif %}
+{% if domain_config and domain_config.env_optional %}
+{% for env in domain_config.env_optional %}
+  # {{ env.name }}: "{{ env.default }}"
+{% endfor %}
+{% endif %}

aes/scaffold/operations.md.jinja

@@ -0,0 +1,33 @@
+# {{ name }} — Operations Memory
+
+> Unified chronological log across all commands.
+> **Read the entire log** when starting any command — entries from other workers give you context.
+> After reading, update your **Read Cursor** below so you know where you left off next time.
+> Append new entries to the Activity Log tagged with your command.
+
+## Workers
+
+| Command | Specialty | Read Cursor |
+|---------|-----------|-------------|
+{% for cmd in workflow_commands %}| {{ cmd.trigger }} | {{ cmd.worker_specialty or cmd.description }} | 0 |
+{% endfor %}
+
+## Activity Log
+
+_No activity recorded yet._
+
+<!-- Append entries in this format:
+1. [/build] YYYY-MM-DD: what was done — outcome
+2. [/train] YYYY-MM-DD: what was done — outcome
+Entries are numbered sequentially. Each command updates its Read Cursor to the
+last entry number it has seen, so it knows what's new next session.
+-->
+
+## Issues & Decisions
+
+_None yet._
+
+<!-- Record cross-cutting issues and decisions here, tagged with command:
+- [/build] Chose SQLite over Postgres for simplicity
+- [/train] Ordinal targets should be reframed as regression
+-->

aes/scaffold/orchestrator.md.jinja

@@ -0,0 +1,95 @@
+{% if domain_config %}
+# {{ name }} — Orchestrator
+
+## Operations Memory
+
+Check `.agent/memory/operations.md` for the current state of each command worker.
+Each command has its own indexed section with activity history and checkmarks.
+{% if domain_config.workflow_commands %}
+Commands tracked:
+{% for cmd in domain_config.workflow_commands %}
+- **{{ cmd.trigger }}** — {{ cmd.worker_specialty or cmd.description }}
+{% endfor %}
+{% endif %}
+
+## Pipeline
+
+```
+{{ domain_config.orchestrator_pipeline }}
+```
+
+## Status Flow
+
+```
+{{ domain_config.orchestrator_status_flow }}
+```
+
+## Decision Tree
+
+```
+FIRST: Check if pipeline is already complete (all items at terminal status).
+  If complete → report status summary, ask user: re-run / new session / re-validate / exit.
+  If not → proceed:
+
+{{ domain_config.orchestrator_decision_tree }}
+```
+
+## When to Stop
+
+{{ domain_config.orchestrator_when_to_stop }}
+{% else %}
+# {{ name }} — Orchestrator
+
+## Pipeline
+
+<!-- AGENT: Define the execution order of skills for this project.
+     If code exists: identify major operations from CLI commands, API endpoints,
+     scripts/, pipeline stages, scheduled jobs. Order them by dependency.
+     If greenfield: ask "What are the main steps in your workflow, in order?" -->
+
+```
+skill_1 → skill_2 → skill_3 → ... → skill_n
+```
+
+## Status Flow
+
+<!-- AGENT: Define entity status transitions.
+     If code exists: look for status columns in models, enums, state machines,
+     workflow definitions, or status fields in database schemas.
+     If greenfield: ask "What states does your primary entity move through?" -->
+
+```
+status_1 → status_2 → ... → status_n
+                               ↗
+                         rejected (any stage)
+```
+
+## Decision Tree
+
+<!-- AGENT: Define the decision logic for processing items.
+     If code exists: trace the main processing loop — what checks happen,
+     what branches exist, what determines success vs failure.
+     If greenfield: ask about decision points and error handling. -->
+
+```
+FIRST: Check if pipeline is already complete (all items at terminal status).
+  If complete → report status summary, ask user: re-run / new session / re-validate / exit.
+  If not → proceed:
+
+for each pending_stage:
+  1. Check prerequisites
+  2. Get items at current status
+  3. For each item:
+     a. Run stage skill
+     b. On success: advance status
+     c. On failure: log error, mark rejected if unrecoverable
+  4. Report results
+```
+
+## When to Stop
+
+- All items at terminal status
+- Resource limits exceeded
+- User requests stop
+- No items to process
+{% endif %}

aes/scaffold/permissions.yaml.jinja

@@ -0,0 +1,151 @@
+{% if domain_config %}
+# .agent/permissions.yaml — Agent Capability Boundaries
+aes_permissions: "1.0"
+
+allow:
+  shell:
+    read:
+      - "git status"
+      - "git log *"
+      - "git diff *"
+      - "ls *"
+{% for cmd in domain_config.permissions_shell_read %}
+      - "{{ cmd }}"
+{% endfor %}
+{% if domain_config.permissions_shell_execute %}
+    execute:
+{% for cmd in domain_config.permissions_shell_execute %}
+      - "{{ cmd }}"
+{% endfor %}
+{% else %}
+    execute: []
+{% endif %}
+
+  files:
+    read: "**/*"
+    write:
+{% for pattern in domain_config.permissions_file_write %}
+      - "{{ pattern }}"
+{% endfor %}
+      - ".agent/memory/**"
+
+deny:
+{% if domain_config.permissions_deny_shell %}
+  shell:
+{% for cmd in domain_config.permissions_deny_shell %}
+    - "{{ cmd }}"
+{% endfor %}
+{% else %}
+  shell: []
+{% endif %}
+  files:
+    write:
+      - ".env"
+      - ".env.*"
+      - "*.pem"
+      - "*.key"
+      - ".git/**"
+
+confirm:
+{% if domain_config.permissions_confirm_shell %}
+  shell:
+{% for cmd in domain_config.permissions_confirm_shell %}
+    - "{{ cmd }}"
+{% endfor %}
+{% else %}
+  shell: []
+{% endif %}
+  files:
+    delete: "**/*"
+{% if domain_config.permissions_confirm_actions %}
+  actions:
+{% for action in domain_config.permissions_confirm_actions %}
+    - "{{ action }}"
+{% endfor %}
+{% else %}
+  actions: []
+{% endif %}
+{% if domain_config.permissions_resource_limits %}
+
+resource_limits:
+  max_cpu_percent: {{ domain_config.permissions_resource_limits.max_cpu_percent }}
+  max_memory_percent: {{ domain_config.permissions_resource_limits.max_memory_percent }}
+{% if domain_config.permissions_resource_limits.check_before is defined %}
+  check_before:
+{% for stage in domain_config.permissions_resource_limits.check_before %}
+    - "{{ stage }}"
+{% endfor %}
+{% endif %}
+{% if domain_config.permissions_resource_limits.on_exceeded is defined %}
+  on_exceeded: "{{ domain_config.permissions_resource_limits.on_exceeded }}"
+{% endif %}
+{% endif %}
+{% else %}
+# .agent/permissions.yaml — Agent Capability Boundaries
+aes_permissions: "1.0"
+
+allow:
+  shell:
+    read:
+      - "git status"
+      - "git log *"
+      - "git diff *"
+      - "ls *"
+    execute:
+{% if language == "python" %}
+      - "python *"
+      - "python -m pytest *"
+      - "pip install *"
+{% elif language == "javascript" or language == "typescript" %}
+      - "node *"
+      - "npm *"
+      - "npx *"
+{% elif language == "go" %}
+      - "go build *"
+      - "go test *"
+      - "go run *"
+{% elif language == "rust" %}
+      - "cargo build *"
+      - "cargo test *"
+      - "cargo run *"
+{% else %}
+      # <!-- AGENT: Add execute permissions for your build/test/run tools.
+      #      If code exists: check package config, Makefile, scripts/ directory.
+      #      If greenfield: infer from tech stack or ask the user. -->
+{% endif %}
+
+  files:
+    read: "**/*"
+    write:
+      # <!-- AGENT: List source directories the agent should be allowed to modify.
+      #      If code exists: identify src/, lib/, app/, tests/, scripts/ directories.
+      #      If greenfield: ask "where will your source code live?" -->
+      - "src/**"
+      - ".agent/memory/**"
+
+deny:
+  shell:
+    # <!-- AGENT: Add project-specific destructive commands to deny.
+    #      If code exists: check for database CLIs, cloud CLIs, or other dangerous tools.
+    #      If greenfield: ask about infrastructure or deployment tools that could be destructive. -->
+    - "rm -rf *"
+    - "chmod 777 *"
+  files:
+    write:
+      - ".env"
+      - ".env.*"
+      - "*.pem"
+      - "*.key"
+      - ".git/**"
+
+confirm:
+  shell:
+    # <!-- AGENT: Add high-impact commands that should require confirmation.
+    #      If code exists: look for deploy, publish, push, or migration commands.
+    #      If greenfield: ask about deployment and release processes. -->
+    - "git push *"
+    - "git reset *"
+  files:
+    delete: "**/*"
+  actions: []
+{% endif %}