Merge pull request #92 from jwm4/docs/fix-ambient-json-schema-docs

Fix ambient.json field documentation to match platform

Author: jwm4

.claude/skills/workflow-creator/SKILL.md

@@ -127,11 +127,7 @@ Create `.ambient/ambient.json` without comments (production-ready JSON):
   "name": "{Workflow Display Name}",
   "description": "{User's description}",
   "systemPrompt": "{Generated system prompt based on workflow type}",
-  "startupPrompt": "{Generated startup prompt}",
-  "results": {
-    "{Artifact Type 1}": "artifacts/{workflow-name}/{path}",
-    "{Artifact Type 2}": "artifacts/{workflow-name}/{path}"
-  }
+  "startupPrompt": "{Generated startup prompt}"
 }
 ```
 
@@ -159,22 +155,15 @@ Before using any slash commands, ensure the workspace is initialized.
 ```
 
 **Startup Prompt Template:**
-```
-Welcome! I'm your {Workflow Type} assistant.
-
-🎯 WHAT I DO:
-{1-2 sentence explanation of workflow purpose}
-
-📋 WORKFLOW PHASES:
-{List phases with brief description}
-
-🚀 AVAILABLE COMMANDS:
-{List each command with one-line description}
 
-💡 GETTING STARTED:
-Run /{first-command} to {action}, or tell me what you'd like to work on.
+NOTE: The `startupPrompt` is sent TO the agent as a hidden user message at
+session start. The user never sees it -- they only see the agent's response.
+Write it as a directive telling the agent how to begin, not as a canned greeting.
 
-What would you like to accomplish today?
+```
+Greet the user and introduce yourself as a {Workflow Type} assistant. Briefly
+explain what you do ({1-2 sentence purpose}), list the available commands
+({list commands}), and ask what they'd like to work on. Keep it concise.
 ```
 
 Show progress:
@@ -443,7 +432,7 @@ You can customize this workflow by:
 1. **Modifying agents:** Edit files in `.claude/agents/`
 2. **Adding commands:** Create new command files in `.claude/commands/`
 3. **Adjusting configuration:** Update `.ambient/ambient.json`
-4. **Changing output paths:** Modify the `results` section in config
+4. **Changing output paths:** Update artifact paths in `systemPrompt`
 
 ## Best Practices
 
@@ -518,62 +507,28 @@ This document provides detailed information about the configuration fields in `.
 
 ### startupPrompt
 - **Type:** string
-- **Purpose:** Initial message when workflow activates
+- **Purpose:** Sent to the agent as a hidden user message at session start; the user never sees it, only the agent's response
 - **Current Value:** See `.ambient/ambient.json`
 - **Guidelines:**
-  - Greet user warmly
-  - List available commands
-  - Provide clear next steps
+  - Write as a directive to the agent (e.g., "Greet the user and introduce yourself as...")
+  - Tell the agent to list available commands and ask what the user needs
+  - Do NOT write it as a canned greeting -- the agent generates its own response
 
 ## Optional Fields
 
 ### results
 - **Type:** object with string values
-- **Purpose:** Maps artifact types to file paths
+- **Purpose:** Documents which artifact types the workflow produces and where
+- **Note:** This field is informational only -- the platform does not read it at runtime
 - **Current Value:** See `.ambient/ambient.json`
 - **Guidelines:** Use glob patterns to match multiple files
 
-### version
-- **Type:** string
-- **Example:** "1.0.0"
-- **Purpose:** Track workflow configuration version
-
-### author
-- **Type:** string or object
-- **Example:** {"name": "Your Name", "email": "you@example.com"}
-- **Purpose:** Identify workflow creator
-
-### tags
-- **Type:** array of strings
-- **Example:** ["bug-fix", "debugging", "testing"]
-- **Purpose:** Categorize workflow for discovery
-
-### icon
-- **Type:** string (emoji)
-- **Example:** "🔧"
-- **Purpose:** Visual identifier in UI
-
 ## Customization Examples
 
-### Adding a new output type
-```json
-"results": {
-  "Existing Output": "artifacts/{workflow-name}/existing/**/*.md",
-  "New Output": "artifacts/{workflow-name}/new/**/*.json"
-}
-```
-
 ### Changing artifact location
 Update all references to the artifact path in:
 1. `systemPrompt` - OUTPUT LOCATIONS section
-2. `results` - Update file paths
-3. Command files - Update ## Output sections
-
-### Adding environment configuration
-```json
-"environment": {
-  "ARTIFACTS_DIR": "artifacts/{workflow-name}",
-  "LOG_LEVEL": "info"
+2. Command files - Update ## Output sections
 }
 ```
 
@@ -824,8 +779,7 @@ As you create files, explain:
 ★ Insight ─────────────────────────────────────
 This configuration file controls how Claude behaves in your workflow:
 - systemPrompt: Defines Claude's role and capabilities
-- startupPrompt: The greeting message users see
-- results: Maps output types to file locations
+- startupPrompt: A directive sent to the agent telling it how to greet the user (the user only sees the agent's response)
 
 The prompts use specific sections (KEY RESPONSIBILITIES, WORKFLOW METHODOLOGY)
 to help Claude understand the workflow structure.

AGENTS.md

@@ -120,8 +120,8 @@ Optional but common:
 | `name` | Yes | Display name in UI (2-5 words) |
 | `description` | Yes | Brief explanation (1-3 sentences) |
 | `systemPrompt` | Yes | Core instructions defining agent behavior |
-| `startupPrompt` | Yes | Initial greeting when workflow activates |
-| `results` | No | Maps artifact names to output paths |
+| `startupPrompt` | Yes | Directive sent to agent as hidden user message at session start (agent responds to it; user sees only the response) |
+| `results` | No | Maps artifact names to output paths (informational only -- not read by the platform) |
 
 ---
 
@@ -282,7 +282,7 @@ cp -r workflows/template-workflow workflows/{new-workflow-name}
 
 - Create new file in `.claude/commands/`
 - Add the command to the `systemPrompt` command list
-- Update `results` in ambient.json if new artifacts are created
+- Optionally update `results` in ambient.json to document new artifacts (informational only)
 
 **Modifying systemPrompt:**
 
@@ -292,8 +292,8 @@ cp -r workflows/template-workflow workflows/{new-workflow-name}
 
 **Changing artifact paths:**
 
-- Update both `systemPrompt` and `results` field
-- Consider backward compatibility
+- Update `systemPrompt` to reference the new paths
+- Optionally update `results` field to match (informational only)
 
 ### Use workflow-editor for Complex Changes
 
@@ -307,7 +307,7 @@ Before committing changes:
 
 1. **Validate JSON**: Ensure `.ambient/ambient.json` is valid
 2. **Check references**: Commands listed in systemPrompt exist as files
-3. **Verify paths**: Output paths in systemPrompt match `results` patterns
+3. **Verify paths**: Output paths in systemPrompt reference the `artifacts/` directory
 
 ### Testing in ACP
 
@@ -427,16 +427,14 @@ The following commands require `required_permissions: ['all']` to run outside th
 "systemPrompt": "You are a helper.\n\n## Commands\n- /diagnose - Run diagnosis"
 ```
 
-### Inconsistent Paths
+### Inconsistent Artifact Paths
 
 ```json
-// ❌ systemPrompt says one thing, results say another
-"systemPrompt": "Write to artifacts/bugs/",
-"results": { "Reports": "output/reports/*.md" }
+// ❌ systemPrompt references a non-standard artifact path
+"systemPrompt": "Write to output/bugs/"
 
-// ✅ Consistent paths
-"systemPrompt": "Write to artifacts/bugfix/",
-"results": { "Reports": "artifacts/bugfix/*.md" }
+// ✅ Use the standard artifacts directory
+"systemPrompt": "Write to artifacts/bugfix/"
 ```
 
 ---
@@ -472,7 +470,7 @@ The following commands require `required_permissions: ['all']` to run outside th
   "name": "Workflow Name",
   "description": "Brief description",
   "systemPrompt": "You are...\n\n## Commands\n...\n\n## Output\nartifacts/...",
-  "startupPrompt": "Welcome! Use /command to start."
+  "startupPrompt": "Greet the user, briefly introduce yourself, and ask what they'd like to work on."
 }
 ```