diff --git a/.claude/skills/workflow-creator/SKILL.md b/.claude/skills/workflow-creator/SKILL.md index b4647370..68da83d5 100644 --- a/.claude/skills/workflow-creator/SKILL.md +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index 007ff268..b574a468 100644 --- a/AGENTS.md +++ b/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." } ``` diff --git a/AMBIENT_JSON_SCHEMA.md b/AMBIENT_JSON_SCHEMA.md index 7300acd2..b4f3538c 100644 --- a/AMBIENT_JSON_SCHEMA.md +++ b/AMBIENT_JSON_SCHEMA.md @@ -1,7 +1,7 @@ # Complete ambient.json Schema **Source**: ambient-code/platform repository analysis -**Date**: 2026-01-25 +**Date**: 2026-03-29 ## Overview @@ -15,15 +15,9 @@ interface AmbientConfig { description: string; // Required systemPrompt: string; // Required startupPrompt: string; // Required - enabled?: boolean; // Optional (default: true) - greeting?: string; // Optional - results?: { // Optional + results?: { // Optional (informational only -- not read by platform) [artifactName: string]: string; // Glob pattern for artifact location }; - rubric?: { // Optional - activationPrompt: string; - schema: object; - }; } ``` @@ -147,104 +141,38 @@ All artifacts go in `artifacts/specsmith/`: ### `startupPrompt` (string, required) -**Purpose**: Initial greeting message when workflow is activated +**Purpose**: Sent to the agent as a hidden user message at session start. The user never sees this text -- they only see the agent's response. Write it as a directive telling the agent how to begin the session, not as a canned greeting. **Guidelines**: -- Friendly and welcoming tone -- Brief introduction to workflow -- List available commands -- Quick-start instructions for first-time users -- 2-5 sentences typical +- Write as an instruction to the agent (e.g., "Greet the user and introduce yourself as...") +- Tell the agent what information to include in its greeting (available commands, purpose, etc.) +- Keep it concise -- 1-3 sentences directing the agent's behavior +- Do NOT write it as a greeting the user would see directly **Examples**: ```json -"startupPrompt": "Welcome to Specsmith Workflow! I'll help you transform feature ideas into implementation-ready plans through structured interviews. Available commands: /spec.interview, /spec.speedrun, /validate. Start with /spec.interview to begin!" - -"startupPrompt": "Hi! I'm your Bug Fix assistant. I'll help you triage, analyze, and fix bugs systematically. Use /fix to start the workflow, or ask me about any bug you'd like to investigate." - -"startupPrompt": "Welcome! I'll help you collect user feedback through structured interviews. I can send results to Jira or GitHub. Use /interview to start, or ask me questions about the workflow." -``` - ---- - -### `enabled` (boolean, optional) - -**Purpose**: Controls whether the workflow appears in the platform UI and API - -**Default**: `true` - -**Guidelines**: - -- Set to `false` to hide a workflow from the OOTB workflow listing -- Workflows with `enabled: false` are completely excluded from the API response -- Omitting the field is equivalent to `enabled: true` -- Useful for hiding work-in-progress or deprecated workflows without removing them +"startupPrompt": "Greet the user and introduce yourself as a spec-driven development assistant. Mention the available commands (/spec.interview, /spec.speedrun, /validate) and suggest starting with /spec.interview." -**Examples**: +"startupPrompt": "Introduce yourself as a bug fix assistant. Briefly explain that you help triage, analyze, and fix bugs systematically. Mention the /fix command and ask the user to describe their bug." -```json -"enabled": false -"enabled": true -``` - ---- - -### `greeting` (string, optional) - -**Purpose**: User-facing welcome message displayed immediately when the workflow is selected, rendered with a typewriter effect - -**Guidelines**: - -- Displayed instantly without LLM generation -- Use markdown formatting (lists, bold, etc.) -- List available slash commands -- Keep concise ā€” this is the first thing users see - -**Example**: - -```json -"greeting": "Welcome to PRD & RFE Creation!\n\nAvailable commands:\nā€¢ /prd.discover ā€” Start product discovery\nā€¢ /prd.create ā€” Draft the PRD\n\nType /prd.discover to get started." -``` - ---- - -### `rubric` (object, optional) - -**Purpose**: Defines evaluation criteria for scoring workflow output quality - -**Structure**: - -- `activationPrompt` (string): Instructions for when and how to evaluate -- `schema` (object): JSON Schema describing the scoring fields - -**Example**: - -```json -"rubric": { - "activationPrompt": "After creating the output, evaluate quality and produce a score out of 25.", - "schema": { - "type": "object", - "properties": { - "completeness": {"type": "number", "description": "Score (1-5)"}, - "clarity": {"type": "number", "description": "Score (1-5)"} - } - } -} +"startupPrompt": "Greet the user and explain that you help collect user feedback through structured interviews. Mention Jira and GitHub integration and suggest using /interview to start." ``` --- ### `results` (object, optional) -**Purpose**: Map artifact names to output file paths/patterns +**Purpose**: Map artifact names to output file paths/patterns for documentation purposes + +**Note**: This field is **not read by the platform**. It serves as human-readable documentation of what a workflow produces and where. The platform discovers artifacts via the hardcoded `artifacts/` directory. **Guidelines**: -- Helps platform UI discover generated artifacts +- Purely informational -- not used by the platform at runtime +- Useful as documentation for workflow authors and users - Uses glob patterns for multiple files -- Purely informational - doesn't enforce output locations - Keys are human-readable artifact names - Values are paths relative to workspace root @@ -296,10 +224,10 @@ workflow-repository/ The platform loads ambient.json at startup: -**File**: `platform/components/runners/claude-code-runner/adapter.py:1314` +**File**: `platform/components/runners/ambient-runner/ambient_runner/platform/config.py` ```python -def _load_ambient_config(self, cwd_path: str) -> dict: +def load_ambient_config(cwd_path: str) -> dict: """Load ambient.json configuration from workflow directory.""" config_path = Path(cwd_path) / ".ambient" / "ambient.json" if not config_path.exists(): @@ -312,9 +240,9 @@ def _load_ambient_config(self, cwd_path: str) -> dict: ### Usage -1. **System prompt injection** (adapter.py:1399): `systemPrompt` is added to Claude's context -2. **Greeting generation** (main.py:970): `startupPrompt` shown at session start -3. **Workspace context** (adapter.py:1335): Configuration available to agents +1. **System prompt injection** (`prompts.py`): `systemPrompt` is appended to the workspace context prompt +2. **Startup directive** (`app.py`): `startupPrompt` sent to agent as hidden user message at session start +3. **Workflow metadata API** (`content.py`): `name`, `description`, and other fields returned via `/content/workflow-metadata` endpoint --- @@ -329,10 +257,7 @@ def _load_ambient_config(self, cwd_path: str) -> dict: **Optional Fields**: -- `enabled` can be omitted (defaults to `true`) -- `greeting` can be omitted (falls back to LLM-generated greeting) -- `results` can be omitted (defaults to empty object) -- `rubric` can be omitted (no quality evaluation) +- `results` can be omitted (informational only -- not read by the platform) **No Strict Validation**: @@ -352,7 +277,7 @@ def _load_ambient_config(self, cwd_path: str) -> dict: "name": "Simple Workflow", "description": "A minimal workflow configuration", "systemPrompt": "You are a helpful assistant. Help users with their tasks.", - "startupPrompt": "Hello! How can I help you today?" + "startupPrompt": "Greet the user and ask how you can help them today." } ``` @@ -363,7 +288,7 @@ def _load_ambient_config(self, cwd_path: str) -> dict: "name": "Feature Planning Workflow", "description": "Plan features through structured interviews and generate implementation specs", "systemPrompt": "You are a feature planning assistant.\n\n## Commands\n- /interview - Start interview\n- /plan - Generate plan\n\n## Output\nWrite all artifacts to artifacts/planning/", - "startupPrompt": "Welcome! Use /interview to start feature planning.", + "startupPrompt": "Greet the user and introduce yourself as a feature planning assistant. Mention the /interview and /plan commands and suggest starting with /interview.", "results": { "Interview Notes": "artifacts/planning/interview.md", "Implementation Plan": "artifacts/planning/plan.md" @@ -378,7 +303,7 @@ def _load_ambient_config(self, cwd_path: str) -> dict: "name": "Specsmith Workflow", "description": "Transform feature ideas into implementation-ready plans through structured interviews with multi-agent collaboration", "systemPrompt": "You are Specsmith, a spec-driven development assistant...\n\n[Extensive system prompt with phases, agents, commands, output structure]\n\n## Phase 1: Interview\n...\n\n## Specialized Agents\n- Quinn (Architect)\n- Maya (Engineer)\n- Alex (QA)\n...", - "startupPrompt": "Welcome to Specsmith! I'll transform your feature ideas into implementation-ready plans. Commands: /spec.interview, /spec.speedrun, /validate", + "startupPrompt": "Greet the user as Specsmith. Explain that you transform feature ideas into implementation-ready plans. List the commands: /spec.interview, /spec.speedrun, /validate. Suggest starting with /spec.interview.", "results": { "Interview Notes": "artifacts/specsmith/interview-notes.md", "Implementation Plan": "artifacts/specsmith/PLAN.md", @@ -406,11 +331,9 @@ def _load_ambient_config(self, cwd_path: str) -> dict: ### Startup Prompt Design -1. **Warm greeting**: Make users feel welcome -2. **Quick value prop**: What problem does this solve? -3. **Command list**: Show available actions -4. **First steps**: How to get started immediately -5. **Keep it brief**: 3-5 sentences maximum +1. **Write as a directive**: Tell the agent what to do, not what to say verbatim +2. **Specify content**: What information should the agent include in its greeting +3. **Keep it brief**: 1-3 sentences directing the agent's behavior ### Results Configuration @@ -471,7 +394,7 @@ workflow-repo/ "name": "My Workflow", "description": "Detailed description of purpose", "systemPrompt": "You are [role].\n\n## Commands\n- /cmd\n\n## Phases\n1. Step one\n\n## Output\nartifacts/my-workflow/", - "startupPrompt": "Welcome! Use /cmd to start.", + "startupPrompt": "Greet the user, briefly describe your purpose, and suggest using /cmd to start.", "results": { "Output": "artifacts/my-workflow/**/*.md" } @@ -484,9 +407,10 @@ workflow-repo/ **Platform Code Locations**: -- Loader: `platform/components/runners/claude-code-runner/adapter.py:1314` -- Usage: `platform/components/runners/claude-code-runner/adapter.py:1399` -- Greeting: `platform/components/runners/claude-code-runner/main.py:970` +- Config loading: `platform/components/runners/ambient-runner/ambient_runner/platform/config.py` +- System prompt injection: `platform/components/runners/ambient-runner/ambient_runner/platform/prompts.py` +- Startup prompt execution: `platform/components/runners/ambient-runner/ambient_runner/app.py` +- Workflow metadata API: `platform/components/runners/ambient-runner/ambient_runner/endpoints/content.py` **Example Workflows**: @@ -505,9 +429,9 @@ workflow-repo/ ## Summary -The `ambient.json` schema has 4 required fields and 4 optional fields, but the `systemPrompt` field is where workflows become powerful. A well-crafted systemPrompt can define complex multi-phase workflows with specialized agents, API integrations, and sophisticated output structures. +The `ambient.json` schema has 4 required fields and 1 optional field, keeping the format lightweight and portable. The `systemPrompt` field is where workflows become powerful -- a well-crafted systemPrompt can define complex multi-phase workflows with specialized agents, API integrations, and sophisticated output structures. **Minimum viable ambient.json**: 4 required string fields (`name`, `description`, `systemPrompt`, `startupPrompt`) -**Maximum sophistication**: Thousands of characters in systemPrompt defining complete development workflows, with `greeting`, `results`, and `rubric` for richer UX +**Optional**: `results` for documenting artifact locations (informational only) -The platform is lenient - missing optional fields default gracefully, allowing both simple and complex workflow configurations. +The platform is lenient -- missing optional fields default gracefully, and extra fields are ignored. diff --git a/WORKFLOW_DEVELOPMENT_GUIDE.md b/WORKFLOW_DEVELOPMENT_GUIDE.md index 7378d9c8..4b012463 100644 --- a/WORKFLOW_DEVELOPMENT_GUIDE.md +++ b/WORKFLOW_DEVELOPMENT_GUIDE.md @@ -100,7 +100,7 @@ In addition to standard Claude Code extensions, ACP workflows **require** an `am "name": "Fix a bug", "description": "Systematic workflow for analyzing, fixing, and verifying software bugs ...", "systemPrompt": "You are Amber, the Ambient Code Platform's expert colleague orchestrating systematic bug resolution. You help developers fix ....", - "startupPrompt": "Welcome to the Bug Fix Workflow! ... Provide a bug description, issue URL, or symptoms you're experiencing, and I'll orchestrate a systematic fix!", + "startupPrompt": "Greet the user and introduce yourself as a bug fix assistant. Ask them to provide a bug description, issue URL, or symptoms to get started.", "results": { "Bug Reports": "artifacts/bugfix/reports/*.md", "Root Cause Analysis": "artifacts/bugfix/analysis/*.md", @@ -119,8 +119,8 @@ In addition to standard Claude Code extensions, ACP workflows **require** an `am | `name` | āœ… | Display name in the UI | | `description` | āœ… | Brief explanation shown in workflow selector | | `systemPrompt` | āœ… | Core instructions defining Claude's behavior | -| `startupPrompt` | āœ… | Initial greeting when workflow activates | -| `results` | āŒ | Maps artifact names to output paths (for UI discovery) | +| `startupPrompt` | āœ… | Directive sent to agent as hidden user message at session start (agent responds to it; user sees only the response) | +| `results` | āŒ | Maps artifact names to output paths (informational only -- not read by the platform) | > šŸ“– See [AMBIENT_JSON_SCHEMA.md](AMBIENT_JSON_SCHEMA.md) for complete field documentation. @@ -423,7 +423,7 @@ cat > workflows/my-workflow/.ambient/ambient.json << 'EOF' "name": "My Workflow", "description": "A workflow that does X, Y, and Z", "systemPrompt": "You are a helpful assistant for...\n\n## Commands\n- /start - Begin the workflow\n\n## Output\nWrite artifacts to artifacts/my-workflow/", - "startupPrompt": "Welcome! Use /start to begin." + "startupPrompt": "Greet the user, briefly describe your purpose, and suggest using /start to begin." } EOF @@ -716,7 +716,7 @@ Before submitting a PR for a new or modified workflow: **Commands & Skills:** - [ ] Commands are in `.claude/commands/` with `.md` extension - [ ] Skills are in `.claude/skills//SKILL.md` with proper frontmatter -- [ ] Output paths in `systemPrompt` match `results` configuration +- [ ] Output paths in `systemPrompt` reference the `artifacts/` directory **Documentation:** - [ ] README.md documents the workflow diff --git a/internal-workflows/template-workflow/.ambient/ambient.json b/internal-workflows/template-workflow/.ambient/ambient.json index d5cef765..bcc5fd2a 100644 --- a/internal-workflows/template-workflow/.ambient/ambient.json +++ b/internal-workflows/template-workflow/.ambient/ambient.json @@ -2,7 +2,7 @@ "name": "Template Workflow", "description": "A comprehensive template workflow demonstrating all available configuration options for the Ambient Code Platform. Use this as a starting point for creating custom workflows.", "systemPrompt": "You are a workflow assistant for the Ambient Code Platform. Your role is to guide users through structured development processes using a combination of slash commands, agent personas, and automated scripts.\n\nKEY RESPONSIBILITIES:\n- Guide users through multi-phase workflows\n- Execute slash commands to perform specific tasks\n- Collaborate with specialized agent personas when needed\n- Generate well-structured artifacts and documentation\n- Maintain consistency and quality throughout the workflow\n\nWORKSPACE NAVIGATION:\n**CRITICAL: Follow these rules to avoid fumbling when looking for files.**\n\nStandard file locations (from workflow root):\n- Config: .ambient/ambient.json (ALWAYS at this path)\n- Agents: .claude/agents/*.md\n- Commands: .claude/commands/*.md\n- Outputs: artifacts/template/\n\nTool selection rules:\n- Use Read for: Known paths, standard files (ambient.json, README.md), files you just created\n- Use Glob for: Discovery (finding multiple files by pattern), unknown locations\n- Use Grep for: Content search, finding files containing specific text\n\nNever glob for standard files:\nāœ… DO: Read .ambient/ambient.json\nāŒ DON'T: Glob **/ambient.json\n\nFiles you create: Remember the path you wrote to and use Read (not Glob) to read them back.\n\nWORKFLOW METHODOLOGY:\nThis is a template workflow that demonstrates the general structure:\n1. INITIALIZE: Set up the workspace and understand requirements\n2. ANALYZE: Examine the problem space and gather context\n3. PLAN: Create a structured plan or specification\n4. EXECUTE: Implement the solution following the plan\n5. VERIFY: Validate the implementation and document results\n\nAVAILABLE COMMANDS:\nUse the following slash commands to execute workflow phases:\n- /init - Initialize the workflow workspace\n- /analyze - Analyze the current state and requirements\n- /plan - Create a detailed plan or specification\n- /execute - Implement the planned solution\n- /verify - Validate and document the results\n\nOUTPUT LOCATIONS:\n- Create all specifications in: artifacts/specs/\n- Create all plans in: artifacts/plans/\n- Create all implementation artifacts in: artifacts/implementation/\n- Create all documentation in: artifacts/docs/\n\nFIRST TIME SETUP:\nBefore using any slash commands, ensure the workspace is initialized. If this is your first time, run the initialization command to set up the required directory structure.", - "startupPrompt": "Welcome! I'm your Ambient Workflow Assistant.\n\nšŸŽÆ GETTING STARTED:\nThis workflow helps you execute structured development processes with the following phases:\n1. Initialize workspace\n2. Analyze requirements\n3. Create plans/specifications\n4. Execute implementation\n5. Verify and document results\n\nšŸ“‹ AVAILABLE COMMANDS:\n- /init - Initialize the workflow workspace and directory structure\n- /analyze - Analyze the problem, codebase, or requirements\n- /plan - Create detailed plans or specifications\n- /execute - Implement the planned solution\n- /verify - Validate results and generate documentation\n\nšŸš€ QUICK START:\nTo begin, run `/init` to set up your workspace, or jump straight to `/analyze [your-description]` if you already know what you want to work on.\n\nšŸ’” TIP:\nEach command guides you through a specific phase of the workflow. You can run them in sequence or jump to any phase based on your needs.\n\nWhat would you like to work on today?", + "startupPrompt": "Greet the user and introduce yourself as a workflow assistant. List the 5 phases (initialize, analyze, plan, execute, verify) and the corresponding commands (/init, /analyze, /plan, /execute, /verify). Suggest starting with /init or jumping to /analyze if they already know what to work on. Ask what they'd like to do.", "results": { "Specifications": "artifacts/specs/**/*.md", "Implementation Plans": "artifacts/plans/**/*.md", diff --git a/workflows/cve-fixer/FIELD_REFERENCE.md b/workflows/cve-fixer/FIELD_REFERENCE.md index e45dc14c..4b01fd84 100644 --- a/workflows/cve-fixer/FIELD_REFERENCE.md +++ b/workflows/cve-fixer/FIELD_REFERENCE.md @@ -30,24 +30,23 @@ This document provides detailed information about the configuration fields in `. ### startupPrompt - **Type:** string -- **Purpose:** Initial message shown 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 and introduce the workflow purpose - - List available commands with brief descriptions - - Provide clear call-to-action for getting started - - Keep concise but informative + - 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 path patterns +- **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 - Organize by artifact type for easy discovery - - Ensure paths match those referenced in commands and systemPrompt **Current Mappings:** ```json @@ -57,70 +56,14 @@ This document provides detailed information about the configuration fields in `. } ``` -### version -- **Type:** string -- **Example:** "1.0.0" -- **Purpose:** Track workflow configuration version for updates and compatibility - -### author -- **Type:** string or object -- **Example:** `{"name": "Your Name", "email": "security@example.com"}` -- **Purpose:** Identify workflow creator and maintainer - -### tags -- **Type:** array of strings -- **Example:** `["security", "cve", "vulnerability", "remediation"]` -- **Purpose:** Categorize workflow for discovery and organization - -### icon -- **Type:** string (emoji) -- **Example:** "šŸ”’" -- **Purpose:** Visual identifier in workflow selection UI - ## Customization Examples -### Adding a new output type - -If you want to track additional artifacts (e.g., "Test Results"): - -```json -"results": { - "Jira CVE Issues": "artifacts/cve-fixer/find/**/*.md", - "Fix Implementations": "artifacts/cve-fixer/fixes/**/*", - "Test Results": "artifacts/cve-fixer/tests/**/*.log" -} -``` - ### Changing artifact location -To use a different base directory (e.g., `security-artifacts/`): +To use a different base directory, update: -1. Update `systemPrompt` OUTPUT LOCATIONS section: -``` -OUTPUT LOCATIONS: -- Create all Jira CVE findings in: security-artifacts/cve-fixer/find/ -- Create all fix implementations in: security-artifacts/cve-fixer/fixes/ -``` - -2. Update `results` paths: -```json -"results": { - "Jira CVE Issues": "security-artifacts/cve-fixer/find/**/*.md", - "Fix Implementations": "security-artifacts/cve-fixer/fixes/**/*" -} -``` - -3. Update all command files in `.claude/commands/` to reference new paths in their ## Output sections - -### Adding environment configuration - -```json -"environment": { - "ARTIFACTS_DIR": "artifacts/cve-fixer", - "SCAN_TOOLS": "snyk,npm-audit,trivy", - "LOG_LEVEL": "info" -} -``` +1. `systemPrompt` OUTPUT LOCATIONS section +2. All command files in `.claude/commands/` to reference new paths in their ## Output sections ### Customizing for specific compliance frameworks diff --git a/workflows/triage/FIELD_REFERENCE.md b/workflows/triage/FIELD_REFERENCE.md index d7afb910..fdc3de13 100644 --- a/workflows/triage/FIELD_REFERENCE.md +++ b/workflows/triage/FIELD_REFERENCE.md @@ -11,12 +11,12 @@ This document describes all available fields and configuration options for the t | `name` | string | Yes | Display name of the workflow | | `description` | string | Yes | Brief description of what the workflow does | | `systemPrompt` | string | Yes | Instructions for the AI assistant on how to execute the workflow | -| `startupPrompt` | string | No | Welcome message shown when the workflow starts | -| `results` | object | No | Map of result categories to file path patterns | +| `startupPrompt` | string | No | Directive sent to agent as hidden user message at session start (agent responds to it; user sees only the response) | +| `results` | object | No | Documents artifact types and locations (informational only -- not read by the platform) | ### Results Configuration -The `results` object maps human-readable names to file path patterns where outputs will be generated: +The `results` object documents what artifacts the workflow produces. Note that this field is **informational only** -- the platform does not read it at runtime. It serves as documentation for workflow authors and users. ```json {