feat: add memory, convergence, colette bridge, templates, progress, effectiveness, git integration
- skills/memory: cross-run learning from recurring findings + lib/archeflow-memory.sh - skills/convergence: oscillation detection + early termination in multi-cycle runs - skills/colette-bridge: auto-inject voice profiles, personas, characters from colette.yaml - skills/templates: workflow/team/archetype gallery with init/save/share - skills/progress: live .archeflow/progress.md during runs - skills/effectiveness: per-archetype signal-to-noise + cost efficiency scoring - skills/git-integration: auto-branch per run, commit per phase, rollback support
This commit is contained in:
322
skills/templates/SKILL.md
Normal file
322
skills/templates/SKILL.md
Normal file
@@ -0,0 +1,322 @@
|
||||
---
|
||||
name: templates
|
||||
description: |
|
||||
Template gallery for sharing workflows, team presets, archetypes, domain configs, and complete
|
||||
setup bundles across ArcheFlow projects. Supports init-from-template, save-as-template, and
|
||||
clone-from-project operations.
|
||||
<example>User: "archeflow init writing-short-story"</example>
|
||||
<example>User: "archeflow template save my-backend-setup"</example>
|
||||
<example>User: "archeflow template list"</example>
|
||||
<example>User: "archeflow init --from ../book.giesing-gschichten"</example>
|
||||
---
|
||||
|
||||
# Template Gallery — Shareable ArcheFlow Configurations
|
||||
|
||||
Workflows, team presets, custom archetypes, and domain configs should be reusable across projects. This skill defines the template system that makes ArcheFlow setups portable and shareable.
|
||||
|
||||
## Template Storage
|
||||
|
||||
Templates live in two locations, with project-local overriding global:
|
||||
|
||||
| Location | Scope | Precedence |
|
||||
|----------|-------|------------|
|
||||
| `.archeflow/templates/` | Project-local | Higher (checked first) |
|
||||
| `~/.archeflow/templates/` | Global (user-wide) | Lower (fallback) |
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/.archeflow/templates/
|
||||
├── workflows/
|
||||
│ ├── kurzgeschichte.yaml
|
||||
│ ├── feature-implementation.yaml
|
||||
│ └── security-review.yaml
|
||||
├── teams/
|
||||
│ ├── story-development.yaml
|
||||
│ ├── backend.yaml
|
||||
│ └── fullstack.yaml
|
||||
├── archetypes/
|
||||
│ ├── story-explorer.md
|
||||
│ ├── story-sage.md
|
||||
│ └── db-specialist.md
|
||||
├── domains/
|
||||
│ ├── writing.yaml
|
||||
│ ├── code.yaml
|
||||
│ └── research.yaml
|
||||
└── bundles/
|
||||
├── writing-short-story/
|
||||
│ ├── manifest.yaml
|
||||
│ ├── team.yaml
|
||||
│ ├── workflow.yaml
|
||||
│ ├── archetypes/
|
||||
│ │ ├── story-explorer.md
|
||||
│ │ └── story-sage.md
|
||||
│ └── domain.yaml
|
||||
└── backend-feature/
|
||||
├── manifest.yaml
|
||||
├── team.yaml
|
||||
├── workflow.yaml
|
||||
└── domain.yaml
|
||||
```
|
||||
|
||||
Individual templates (workflows/, teams/, archetypes/, domains/) are single files that can be used standalone. Bundles are complete setups that include everything a project needs.
|
||||
|
||||
---
|
||||
|
||||
## Bundle Manifest
|
||||
|
||||
Every bundle has a `manifest.yaml` that declares what it contains, what it requires, and what variables it exposes.
|
||||
|
||||
```yaml
|
||||
name: writing-short-story
|
||||
description: "Complete setup for short fiction writing with ArcheFlow"
|
||||
version: 1
|
||||
domain: writing
|
||||
includes:
|
||||
team: story-development.yaml
|
||||
workflow: kurzgeschichte.yaml
|
||||
archetypes:
|
||||
- story-explorer.md
|
||||
- story-sage.md
|
||||
domain: writing.yaml
|
||||
requires:
|
||||
- colette.yaml # Project must have this file
|
||||
variables:
|
||||
target_words: 6000 # Default, can be overridden at init time
|
||||
max_cycles: 2 # Default, can be overridden at init time
|
||||
```
|
||||
|
||||
### Manifest Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Bundle identifier (used in `archeflow init <name>`) |
|
||||
| `description` | Yes | Human-readable description |
|
||||
| `version` | No | Bundle version (integer, default 1) |
|
||||
| `domain` | No | Domain this bundle is designed for |
|
||||
| `includes` | Yes | Map of file types to filenames within the bundle |
|
||||
| `requires` | No | List of files that must exist in the target project |
|
||||
| `variables` | No | Key-value pairs with defaults, overridable at init |
|
||||
|
||||
### Includes Types
|
||||
|
||||
| Key | Target location in `.archeflow/` | Accepts |
|
||||
|-----|----------------------------------|---------|
|
||||
| `team` | `teams/<filename>` | Single YAML file |
|
||||
| `workflow` | `workflows/<filename>` | Single YAML file |
|
||||
| `archetypes` | `archetypes/<filename>` | List of Markdown files |
|
||||
| `domain` | `domains/<filename>` | Single YAML file |
|
||||
| `hooks` | `hooks.yaml` | Single YAML file |
|
||||
|
||||
---
|
||||
|
||||
## Operations
|
||||
|
||||
### `archeflow init <bundle-name>`
|
||||
|
||||
Initialize a project's `.archeflow/` directory from a named bundle.
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Search for the bundle:
|
||||
- `.archeflow/templates/bundles/<name>/manifest.yaml` (project-local)
|
||||
- `~/.archeflow/templates/bundles/<name>/manifest.yaml` (global)
|
||||
- If not found: error with list of available bundles
|
||||
2. Read `manifest.yaml`
|
||||
3. Check `requires`:
|
||||
- For each required file, verify it exists in the project root
|
||||
- If missing: error with `"Required file not found: <file>. This bundle requires it."`
|
||||
4. Check for existing `.archeflow/` setup:
|
||||
- If `.archeflow/teams/`, `.archeflow/workflows/`, etc. already contain files: warn and ask before overwriting
|
||||
- Never silently overwrite existing configuration
|
||||
5. Copy files from bundle to `.archeflow/`:
|
||||
- `team` → `.archeflow/teams/<filename>`
|
||||
- `workflow` → `.archeflow/workflows/<filename>`
|
||||
- `archetypes` → `.archeflow/archetypes/<filename>` (each file)
|
||||
- `domain` → `.archeflow/domains/<filename>`
|
||||
- `hooks` → `.archeflow/hooks.yaml`
|
||||
6. Create `.archeflow/config.yaml` with variables from manifest:
|
||||
```yaml
|
||||
# Generated by archeflow init from bundle: <name>
|
||||
bundle: <name>
|
||||
bundle_version: <version>
|
||||
initialized: <timestamp>
|
||||
variables:
|
||||
target_words: 6000
|
||||
max_cycles: 2
|
||||
```
|
||||
7. Print setup summary:
|
||||
```
|
||||
ArcheFlow initialized from bundle: <name>
|
||||
Team: <team filename> → .archeflow/teams/
|
||||
Workflow: <workflow filename> → .archeflow/workflows/
|
||||
Archetypes: <count> files → .archeflow/archetypes/
|
||||
Domain: <domain filename> → .archeflow/domains/
|
||||
Config: .archeflow/config.yaml (variables: target_words=6000, max_cycles=2)
|
||||
|
||||
Ready to run: archeflow:run
|
||||
```
|
||||
|
||||
### `archeflow init --from <project-path>`
|
||||
|
||||
Clone another project's ArcheFlow setup into the current project.
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Verify `<project-path>/.archeflow/` exists
|
||||
2. Copy these subdirectories (if they exist):
|
||||
- `teams/`
|
||||
- `workflows/`
|
||||
- `archetypes/`
|
||||
- `domains/`
|
||||
- `config.yaml`
|
||||
- `hooks.yaml`
|
||||
3. Do NOT copy (run-specific data):
|
||||
- `events/`
|
||||
- `artifacts/`
|
||||
- `context/` (generated by colette-bridge, project-specific)
|
||||
- `templates/` (project-local templates stay local)
|
||||
4. Warn if target `.archeflow/` already has files
|
||||
5. Print summary of what was copied
|
||||
|
||||
### `archeflow template save <name>`
|
||||
|
||||
Save the current project's `.archeflow/` setup as a reusable template bundle.
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Verify `.archeflow/` exists and has content
|
||||
2. Create bundle directory: `~/.archeflow/templates/bundles/<name>/`
|
||||
- If it already exists: warn and ask before overwriting
|
||||
3. Copy from `.archeflow/` to bundle:
|
||||
- `teams/*.yaml` → bundle `team` (first file, or prompt if multiple)
|
||||
- `workflows/*.yaml` → bundle `workflow` (first file, or prompt if multiple)
|
||||
- `archetypes/*.md` → bundle `archetypes/`
|
||||
- `domains/*.yaml` → bundle `domain` (first file, or prompt if multiple)
|
||||
- `hooks.yaml` → bundle (if exists)
|
||||
4. Generate `manifest.yaml`:
|
||||
```yaml
|
||||
name: <name>
|
||||
description: "Saved from <project directory name>"
|
||||
version: 1
|
||||
domain: <from domain yaml if present>
|
||||
includes:
|
||||
team: <filename>
|
||||
workflow: <filename>
|
||||
archetypes: [<filenames>]
|
||||
domain: <filename>
|
||||
requires: []
|
||||
variables: <from config.yaml variables section if present>
|
||||
```
|
||||
5. Print summary:
|
||||
```
|
||||
Template saved: <name>
|
||||
Location: ~/.archeflow/templates/bundles/<name>/
|
||||
Files: <count> files
|
||||
Use with: archeflow init <name>
|
||||
```
|
||||
|
||||
### `archeflow template list`
|
||||
|
||||
List all available templates — both individual files and bundles, from both global and project-local locations.
|
||||
|
||||
**Output format:**
|
||||
|
||||
```
|
||||
ArcheFlow Templates
|
||||
====================
|
||||
|
||||
Bundles:
|
||||
writing-short-story Complete setup for short fiction writing [global]
|
||||
backend-feature Backend feature implementation [global]
|
||||
my-project-setup Saved from book.giesing-gschichten [global]
|
||||
|
||||
Individual Templates:
|
||||
Workflows:
|
||||
kurzgeschichte.yaml [global]
|
||||
feature-implementation.yaml [global]
|
||||
Teams:
|
||||
story-development.yaml [global]
|
||||
backend.yaml [global]
|
||||
Archetypes:
|
||||
story-explorer.md [global]
|
||||
story-sage.md [global]
|
||||
Domains:
|
||||
writing.yaml [global]
|
||||
code.yaml [global]
|
||||
```
|
||||
|
||||
### `archeflow template share <name> <path>`
|
||||
|
||||
Export a template bundle to a directory for sharing (e.g., via git, email, file share).
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Find the bundle (global or local)
|
||||
2. Copy the entire bundle directory to `<path>/<name>/`
|
||||
3. Print the path and a one-liner for importing:
|
||||
```
|
||||
Exported: <path>/<name>/
|
||||
To import: cp -r <path>/<name> ~/.archeflow/templates/bundles/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variable Substitution
|
||||
|
||||
Bundle manifests can define variables with defaults. These are stored in `.archeflow/config.yaml` after init and can be overridden:
|
||||
|
||||
- At init time: `archeflow init writing-short-story --set target_words=8000`
|
||||
- After init: edit `.archeflow/config.yaml` directly
|
||||
|
||||
Variables are available to workflows and the run skill via config:
|
||||
|
||||
```yaml
|
||||
# In a workflow, reference variables:
|
||||
phases:
|
||||
do:
|
||||
description: |
|
||||
Draft the story. Target: ${target_words} words.
|
||||
```
|
||||
|
||||
Variable substitution happens at run time, not at init time. The workflow file contains the `${variable}` placeholder; the run skill reads `.archeflow/config.yaml` and substitutes before passing to agents.
|
||||
|
||||
---
|
||||
|
||||
## Individual Template Usage
|
||||
|
||||
Not everything needs a bundle. Individual templates can be copied directly:
|
||||
|
||||
```bash
|
||||
# Copy a single workflow
|
||||
cp ~/.archeflow/templates/workflows/kurzgeschichte.yaml .archeflow/workflows/
|
||||
|
||||
# Copy a single archetype
|
||||
cp ~/.archeflow/templates/archetypes/story-explorer.md .archeflow/archetypes/
|
||||
|
||||
# Copy a team preset
|
||||
cp ~/.archeflow/templates/teams/story-development.yaml .archeflow/teams/
|
||||
```
|
||||
|
||||
The `archeflow init` command handles bundles. For individual files, manual copy or the helper script (`lib/archeflow-init.sh`) can be used.
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **`archeflow:run`** — Reads `.archeflow/config.yaml` for variables, applies them during run initialization
|
||||
- **`archeflow:domains`** — Domain YAML from templates is loaded like any other domain config
|
||||
- **`archeflow:custom-archetypes`** — Archetype .md files from templates work identically to hand-written ones
|
||||
- **`archeflow:workflow-design`** — Workflow YAML from templates follows the same schema
|
||||
- **`archeflow:colette-bridge`** — Bundle `requires: [colette.yaml]` ensures the bridge has what it needs
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Bundles are self-contained.** Everything needed to set up a project is in the bundle directory. No external dependencies beyond `requires`.
|
||||
2. **Never silently overwrite.** Init warns before replacing existing files. Templates are helpers, not bulldozers.
|
||||
3. **Global + local layering.** Project-local templates override global ones. This allows per-project customization without polluting the global registry.
|
||||
4. **Skip run data.** Events, artifacts, and context are run-specific. Templates carry only configuration.
|
||||
5. **Variables are late-bound.** Substitution happens at run time, not template time. This keeps templates generic.
|
||||
6. **Plain files, no magic.** Templates are just directories of YAML and Markdown files. No databases, no registries, no lock files.
|
||||
Reference in New Issue
Block a user