feat: make prompt-to-profile workflow literal

codegraphtheory · codegraphtheory · commit 9d669ff13df8 · 2026-06-25T15:02:11.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to this Hermes profile distribution are documented here.
 
+## 0.4.0
+
+- Rebuilt the README around the literal prompt-to-installable-profile-repo workflow.
+- Clarified every usage path so it ends in validation and `hermes profile install`.
+- Updated the installed profile instructions to require repository creation, validation, and optional smoke install when users ask for a new profile.
+- Updated the bundled `profile-craft` skill with a prompt-to-repo workflow.
+- Added the interactive profile-builder demo script to the documented usage path.
+- Fixed generated `config.yaml` model keys so installed template and generated profiles resolve models correctly in Hermes.
+- Fixed prompt-to-repo generation from an installed profile so seeded runtime skills are not copied into generated repos.
+
 ## 0.3.0
 
 - Clarified that this repository is a developer authoring system built on top of Hermes Agent's native profile distribution runtime.
diff --git a/README.md b/README.md
diff --git a/SOUL.md b/SOUL.md
@@ -1,19 +1,23 @@
 # Hermes Profile Architect
 
-You are Hermes Profile Architect, a specialist agent for designing, validating, and improving Hermes Agent profile distributions.
+You are Hermes Profile Architect, a specialist agent for turning a user's prompt into an installable Hermes Agent profile repository.
+
+Your primary job is literal, not metaphorical: when the user describes a desired profile, create a repository directory that can be validated and installed with `hermes profile install`.
 
 ## First principles
 
-1. Profiles are products. They need a clear user, scope, install path, safety model, and maintenance workflow.
-2. Instructions must be operational. A profile should change behavior in concrete ways, not just describe a personality.
-3. Secrets never belong in git. Examples must be placeholders only.
-4. Tools and skills must match the stated mission. Extra capability increases risk and prompt load.
-5. Validation is part of authoring. A profile is not done until the validator passes.
+1. Prompt to repo is the core product. A good answer produces files, not only advice.
+2. Profiles are products. They need a clear user, scope, install path, safety model, and maintenance workflow.
+3. Instructions must be operational. A profile should change behavior in concrete ways, not just describe a personality.
+4. Secrets never belong in git. Examples must be placeholders only.
+5. Tools and skills must match the stated mission. Extra capability increases risk and prompt load.
+6. Validation is part of authoring. A profile is not done until the validator passes or the blocker is stated clearly.
 
 ## Scope
 
 You help users:
 
+- Turn a natural-language profile idea into a complete repository directory.
 - Create focused Hermes profile distributions.
 - Write strong `SOUL.md` identity documents.
 - Design bundled skills and skill loading rules.
@@ -24,19 +28,49 @@ You help users:
 
 ## Interactive profile creation
 
-When a user asks you to create a new Hermes profile, do not answer with a loose plan. Create a params YAML file using `templates/profile.params.yaml` as the schema reference, then run:
+When a user asks you to create a new Hermes profile, do not stop at a plan. Produce an installable repository.
+
+Default workflow:
+
+1. Ask only for missing essentials: profile name, mission, target user, required integrations, data sensitivity, risk level, and preferred output style.
+2. If the user provided enough information, proceed with sensible defaults.
+3. Create a params YAML file using `templates/profile.params.yaml` as the schema reference.
+4. Run:
 
 ```bash
 python3 scripts/generate_profile.py --params <params.yaml> --output <target-dir>
 ```
 
-After generation, run:
+5. Run:
 
 ```bash
 python3 <target-dir>/scripts/validate_profile.py <target-dir>
 ```
 
-Ask only for missing essentials: profile name, mission, target user, required integrations, risk level, and preferred output style. If the user provides enough information, proceed with sensible defaults.
+6. If Hermes is available, smoke install the generated repo:
+
+```bash
+hermes profile install <target-dir> --name <smoke-name> --yes --force
+```
+
+7. Report the generated repository path, validation output, smoke-install output if run, and the next publish command.
+
+## Minimum generated repository
+
+A prompt-to-repo result should include, at minimum:
+
+- `SOUL.md`
+- `distribution.yaml`
+- `README.md`
+- `config.yaml`
+- `.env.EXAMPLE`
+- `AGENTS.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `requirements.txt`
+- `Makefile`
+- `scripts/validate_profile.py`
+- at least one bundled skill when the mission benefits from a reusable procedure
 
 ## Refusals
 
@@ -50,10 +84,10 @@ Refuse to help create profiles that:
 
 ## Tool-use expectations
 
-When editing a profile repository:
+When editing or creating a profile repository:
 
-1. Inspect the file tree first.
-2. Read `AGENTS.md` and `distribution.yaml`.
+1. Inspect the file tree first when a repo already exists.
+2. Read `AGENTS.md` and `distribution.yaml` when present.
 3. Make focused changes.
 4. Run `python3 scripts/validate_profile.py .`.
 5. Report actual validation output.
@@ -62,11 +96,13 @@ When editing a profile repository:
 
 Prefer concise, actionable output:
 
-- What changed.
-- What command was run.
+- Generated repository path.
+- Files changed or created.
+- Commands run.
 - Whether validation passed.
+- Whether smoke install passed or why it was skipped.
 - What the user should do next.
 
 ## Quality bar
 
-A good profile is installable, explainable, auditable, and safe to publish.
+A good profile is installable, explainable, auditable, safe to publish, and easy for another user to install from GitHub.
diff --git a/config.yaml b/config.yaml
@@ -1,6 +1,6 @@
 model:
-  default: anthropic/claude-sonnet-4
   provider: openrouter
+  model: anthropic/claude-sonnet-4
 toolsets:
   - file
   - terminal
diff --git a/distribution.yaml b/distribution.yaml
@@ -1,6 +1,6 @@
 name: hermes-profile-template
-version: 0.3.0
-description: "Starter distribution for building custom Hermes Agent profiles with AI assistance."
+version: 0.4.0
+description: "Prompt-to-repo authoring system for building installable Hermes Agent profile distributions."
 hermes_requires: ">=0.12.0"
 author: "CodeGraphTheory"
 license: "MIT"
diff --git a/docs/interactive-profile-builder-demo.md b/docs/interactive-profile-builder-demo.md
@@ -0,0 +1,213 @@
+# Demo script: install the template as a profile builder
+
+This demo shows the most interesting workflow in this repository: install the template itself as a Hermes profile, then use that profile to create a new installable Hermes profile distribution.
+
+Target length: 2 to 3 minutes.
+
+## Demo goal
+
+Show that `hermes-profile-template` is not only a static GitHub template. It can also be installed as a Hermes profile that helps a user design, generate, validate, and publish new profile distributions.
+
+## Safety setup
+
+Use a clean demo workspace so no personal files, API keys, sessions, or memories appear on screen.
+
+```bash
+export DEMO_ROOT="/tmp/hermes-profile-builder-demo"
+export HERMES_HOME="$DEMO_ROOT/hermes-home"
+rm -rf "$DEMO_ROOT"
+mkdir -p "$DEMO_ROOT"
+cd "$DEMO_ROOT"
+```
+
+Before recording, verify you are not showing secrets:
+
+```bash
+printenv | grep -Ei 'api|token|key|secret|password' || true
+```
+
+If that prints anything sensitive, clear the terminal before recording.
+
+## Opening narration
+
+"I am going to install `hermes-profile-template` as a Hermes profile called `profile-architect`. Then I will use it to create a new specialized profile distribution in a few minutes. The result is a normal GitHub-ready Hermes profile repo with validation, metadata, docs, and safe defaults."
+
+## Scene 1: Install the template as a Hermes profile
+
+Command:
+
+```bash
+hermes profile install github.com/codegraphtheory/hermes-profile-template \
+  --name profile-architect \
+  --alias \
+  --yes
+```
+
+Narration:
+
+"Hermes core handles profile install and isolation. This repository supplies the authoring workflow: profile design prompts, generation scripts, validation, CI, and release hygiene."
+
+Expected beats to show:
+
+- install completes successfully
+- profile path is shown
+- alias `profile-architect` is available
+
+Optional verification:
+
+```bash
+hermes profile info profile-architect
+```
+
+## Scene 2: Ask the profile builder to create a new profile
+
+Start the profile:
+
+```bash
+profile-architect chat
+```
+
+Paste this prompt:
+
+```text
+Create a Hermes profile distribution for a database migration reviewer.
+
+Use case:
+- Reviews SQL migration diffs before deploy.
+- Flags destructive operations like dropped columns, table rewrites, missing rollback plans, unsafe locks, and irreversible data changes.
+- Produces a short risk summary and a rollback checklist.
+
+Repository requirements:
+- Write the generated profile under /tmp/hermes-profile-builder-demo/database-migration-reviewer.
+- Include a clear SOUL.md, distribution.yaml, README.md, config.yaml, .env.EXAMPLE, AGENTS.md, CONTRIBUTING.md, SECURITY.md, and one bundled skill for migration review.
+- Run validation before finishing.
+- Do not use real credentials.
+```
+
+Narration while it works:
+
+"The profile builder turns a product description into a structured profile distribution. The important part is that it does not stop at prose. It should write files and run validation."
+
+## Scene 3: Show the generated repository
+
+In a second terminal, or after the profile returns:
+
+```bash
+cd /tmp/hermes-profile-builder-demo/database-migration-reviewer
+find . -maxdepth 2 -type f | sort
+```
+
+Show the key files:
+
+```bash
+sed -n '1,120p' distribution.yaml
+sed -n '1,80p' SOUL.md
+sed -n '1,100p' README.md
+```
+
+Narration:
+
+"This is now an installable Hermes profile distribution. It has a manifest, agent instructions, docs, environment examples, and bundled skills. It is ready for a GitHub repository after review."
+
+## Scene 4: Validate and smoke install
+
+Run validation from the generated profile root:
+
+```bash
+python3 scripts/validate_profile.py .
+```
+
+If the generated profile includes a Makefile:
+
+```bash
+make validate
+```
+
+Smoke install it into the same temporary Hermes home:
+
+```bash
+hermes profile install . --name migration-reviewer-demo --yes --force
+hermes profile info migration-reviewer-demo
+```
+
+Narration:
+
+"The final check is not just that files exist. Hermes can install the generated profile as a real isolated profile. That is the difference between a README template and an installable profile distribution."
+
+## Scene 5: Close with the publishing path
+
+Show the final publish commands without running them:
+
+```bash
+git init -b main
+git add .
+git commit -m "feat: initial database migration reviewer profile"
+git remote add origin git@github.com:YOUR_ORG/database-migration-reviewer.git
+git push -u origin main
+```
+
+Narration:
+
+"From here, publish the generated directory as a GitHub repo. Users can install it with one command:"
+
+```bash
+hermes profile install github.com/YOUR_ORG/database-migration-reviewer --alias
+```
+
+## Cleanup
+
+After recording:
+
+```bash
+hermes profile delete profile-architect --yes || true
+hermes profile delete migration-reviewer-demo --yes || true
+rm -rf /tmp/hermes-profile-builder-demo
+```
+
+## Short version for a 60-second cut
+
+1. Install builder:
+
+```bash
+hermes profile install github.com/codegraphtheory/hermes-profile-template --name profile-architect --alias --yes
+```
+
+2. Launch:
+
+```bash
+profile-architect chat
+```
+
+3. Prompt:
+
+```text
+Create a Hermes profile distribution for a database migration reviewer. Write it to /tmp/hermes-profile-builder-demo/database-migration-reviewer and run validation before finishing.
+```
+
+4. Show output:
+
+```bash
+cd /tmp/hermes-profile-builder-demo/database-migration-reviewer
+find . -maxdepth 2 -type f | sort
+python3 scripts/validate_profile.py .
+hermes profile install . --name migration-reviewer-demo --yes --force
+```
+
+## Title ideas
+
+- "Turn a prompt into an installable Hermes profile repo"
+- "Using Hermes to build Hermes profiles"
+- "From idea to validated agent profile in 3 minutes"
+
+## Thumbnail text
+
+```text
+Prompt to Profile Repo
+Hermes Profile Template
+```
+
+## Description for posting
+
+```text
+Demo: install hermes-profile-template as a Hermes profile builder, ask it for a database migration reviewer, then validate and smoke-install the generated profile distribution.
+```
diff --git a/scripts/generate_profile.py b/scripts/generate_profile.py
@@ -132,8 +132,8 @@ def render_config(params: dict[str, Any]) -> str:
     return yaml.safe_dump(
         {
             "model": {
-                "default": str(params.get("model_default") or "anthropic/claude-sonnet-4"),
                 "provider": str(params.get("model_provider") or "openrouter"),
+                "model": str(params.get("model_default") or "anthropic/claude-sonnet-4"),
             },
             "toolsets": toolsets,
             "agent": {"max_turns": max_turns, "tool_use_enforcement": True},
@@ -399,10 +399,22 @@ def render_params_example(slug: str, display_name: str, description: str, author
 
 def copy_support_files(template_root: Path, output: Path) -> None:
     ignore = shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store")
-    for rel in ["scripts", "skills", ".github"]:
+    for rel in ["scripts", ".github"]:
         src = template_root / rel
         if src.exists():
             shutil.copytree(src, output / rel, dirs_exist_ok=True, ignore=ignore)
+    # When this repository is installed as a Hermes profile, Hermes may seed the
+    # profile with many bundled user skills. Do not copy that entire runtime
+    # skills directory into generated repos. Only copy this template's own
+    # authoring skill as a starter example.
+    profile_craft = template_root / "skills" / "profile-craft"
+    if profile_craft.exists():
+        shutil.copytree(
+            profile_craft,
+            output / "skills" / "profile-craft",
+            dirs_exist_ok=True,
+            ignore=ignore,
+        )
     for rel in ["LICENSE", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", "requirements.txt", "Makefile"]:
         src_file = template_root / rel
         if src_file.exists():
diff --git a/skills/profile-craft/SKILL.md b/skills/profile-craft/SKILL.md
