1use crate::cli::args::GetFoundryHelpArgs;
4use crate::types::responses::{
5 FoundryResponse, GetFoundryHelpResponse, HelpContent, ValidationStatus,
6};
7use anyhow::Result;
8
9pub async fn execute(args: GetFoundryHelpArgs) -> Result<FoundryResponse<GetFoundryHelpResponse>> {
10 let topic = args.topic.as_deref().unwrap_or("overview");
11
12 let content = match topic {
13 "workflows" => create_workflows_help(),
14 "decision-points" => create_decision_points_help(),
15 "content-examples" => create_content_examples_help(),
16 "project-structure" => create_project_structure_help(),
17 "parameter-guidance" => create_parameter_guidance_help(),
18 "tool-capabilities" => create_tool_capabilities_help(),
19 "edit-commands" => create_edit_commands_help(),
20 _ => create_overview_help(),
21 };
22
23 let next_steps = vec![
24 "Available help topics: workflows, decision-points, content-examples, project-structure, parameter-guidance, tool-capabilities, edit-commands".to_string(),
25 "Choose topics based on what you need guidance for".to_string(),
26 "Use decision-points topic to understand when each tool is appropriate".to_string(),
27 "Use edit-commands topic for deterministic, idempotent spec edits with examples".to_string(),
28 ];
29
30 let workflow_hints = vec![
31 "Help topics provide user-driven decision support, not automated sequences".to_string(),
32 "All commands return JSON for programmatic consumption".to_string(),
33 "Content must be provided by LLMs as arguments - Foundry manages structure only"
34 .to_string(),
35 "Always wait for user intent before suggesting tools".to_string(),
36 ];
37
38 Ok(FoundryResponse {
39 data: GetFoundryHelpResponse {
40 topic: topic.to_string(),
41 content,
42 },
43 next_steps,
44 validation_status: ValidationStatus::Complete,
45 workflow_hints,
46 })
47}
48
49fn create_overview_help() -> HelpContent {
50 HelpContent {
51 title: "Foundry - Project Management for AI Coding Assistants".to_string(),
52 description: "Foundry is a CLI tool that manages project structure in ~/.foundry/ to help LLMs maintain context about software projects through structured specifications. Foundry is content-agnostic - LLMs provide ALL content as arguments, Foundry manages file structure.".to_string(),
53 examples: vec![
54 "{\"name\": \"create_project\", \"arguments\": {\"project_name\": \"my-app\", \"vision\": \"...\", \"tech_stack\": \"...\", \"summary\": \"...\"}}".to_string(),
55 "{\"name\": \"load_project\", \"arguments\": {\"project_name\": \"my-app\"}} # Load complete project context".to_string(),
56 "{\"name\": \"create_spec\", \"arguments\": {\"project_name\": \"my-app\", \"feature_name\": \"user_auth\", \"spec\": \"...\", \"notes\": \"...\", \"tasks\": \"...\"}}".to_string(),
57 "{\"name\": \"list_projects\", \"arguments\": {}} # Discover available projects".to_string(),
58 ],
59 workflow_guide: vec![
60 "Tools available based on user intent - no fixed sequences".to_string(),
61 "Use get_foundry_help with decision-points topic for guidance on tool selection".to_string(),
62 "All content (vision, specs, notes) must be provided by LLMs".to_string(),
63 "Foundry creates structured file organization for consistent context".to_string(),
64 "Always wait for user to express intent before suggesting next tools".to_string(),
65 ],
66 }
67}
68
69fn create_workflows_help() -> HelpContent {
70 HelpContent {
71 title: "User-Driven Foundry Usage Patterns".to_string(),
72 description: "Guidance for using Foundry tools based on user intent and project context, emphasizing user-driven decisions rather than automated sequences.".to_string(),
73 examples: vec![
74 "# When user expresses intent to start a new project:".to_string(),
75 "→ Ask user to provide vision, tech-stack, and summary content".to_string(),
76 "→ Use: {\"name\": \"create_project\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"vision\": \"...\", \"tech_stack\": \"...\", \"summary\": \"...\"}}".to_string(),
77 "→ Wait for user to express what they want to work on next".to_string(),
78 "".to_string(),
79 "# When user wants to work with existing codebase:".to_string(),
80 "→ Use analysis tools (codebase_search, grep_search, read_file) to understand code".to_string(),
81 "→ Create project structure based on your analysis findings".to_string(),
82 "→ Use: {\"name\": \"analyze_project\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"vision\": \"...\", \"tech_stack\": \"...\", \"summary\": \"...\"}}".to_string(),
83 "".to_string(),
84 "# When user mentions a specific feature to implement:".to_string(),
85 "→ Ask user to describe feature requirements and approach".to_string(),
86 "→ Use: {\"name\": \"create_spec\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"feature_name\": \"FEATURE_NAME\", \"spec\": \"...\", \"notes\": \"...\", \"tasks\": \"...\"}}".to_string(),
87 "→ Let user guide implementation approach".to_string(),
88 "".to_string(),
89 "# When user wants to continue previous work:".to_string(),
90 "→ Use: {\"name\": \"list_projects\", \"arguments\": {}} to show available options".to_string(),
91 "→ Use: {\"name\": \"load_project\", \"arguments\": {\"project_name\": \"PROJECT_NAME\"}} to get project context".to_string(),
92 "→ Ask user what they want to work on specifically".to_string(),
93 "".to_string(),
94 "# When user wants to make targeted updates to existing specs:".to_string(),
95 "→ Use: {\"name\": \"load_spec\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"spec_name\": \"SPEC_NAME\"}} to see current content".to_string(),
96 "→ For small targeted changes (mark task complete, add single item, append to a section): use update_spec with edit commands".to_string(),
97 "→ Commands available: set_task_status, upsert_task, append_to_section".to_string(),
98 ],
99 workflow_guide: vec![
100 "Always wait for user intent before suggesting tools".to_string(),
101 "Provide options and capabilities, not directive sequences".to_string(),
102 "Always provide complete content in arguments - never expect Foundry to generate content".to_string(),
103 "Use validate_content to check content quality before creating projects/specs".to_string(),
104 "Ask clarifying questions when user intent is unclear".to_string(),
105 "Let users drive the workflow - tools support user goals".to_string(),
106 "For targeted updates, use edit commands with precise selectors (task_text, section)".to_string(),
107 "Always load current content before editing; copy exact task text and headers".to_string(),
108 ],
109 }
110}
111
112fn create_content_examples_help() -> HelpContent {
113 HelpContent {
114 title: "Content Examples and Markdown Formatting Guidelines".to_string(),
115 description: "Comprehensive formatting standards, content templates, and markdown structure guidelines for all foundry content types.".to_string(),
116 examples: vec![
117 "# MARKDOWN FORMATTING STANDARDS".to_string(),
118 "".to_string(),
119 "## Header Hierarchy:".to_string(),
120 "# Main Document Title (for specs only)".to_string(),
121 "## Major Sections (Problem, Requirements, Implementation)".to_string(),
122 "### Subsections (API Design, Database Schema, Error Handling)".to_string(),
123 "#### Minor Details (specific implementation notes)".to_string(),
124 "".to_string(),
125 "## Lists and Structure:".to_string(),
126 "- Use bullet points for features, requirements, considerations".to_string(),
127 "1. Use numbered lists for sequential steps or priorities".to_string(),
128 "- [ ] Use checkboxes for task lists (uncompleted)".to_string(),
129 "- [x] Use checked boxes for completed tasks".to_string(),
130 "".to_string(),
131 "## Code and Technical Content:".to_string(),
132 "```rust".to_string(),
133 "// Use language-specific code blocks".to_string(),
134 "fn example() { }".to_string(),
135 "```".to_string(),
136 "`inline code` for variables, commands, or short snippets".to_string(),
137 "".to_string(),
138 "## Tables for Complex Information:".to_string(),
139 "| API Endpoint | Method | Purpose |".to_string(),
140 "| ------------ | ------ | ------- |".to_string(),
141 "| /api/users | GET | List users |".to_string(),
142 "".to_string(),
143 "# VISION CONTENT TEMPLATE (200+ chars):".to_string(),
144 "".to_string(),
145 "## Problem".to_string(),
146 "[Specific problem statement with context and impact]".to_string(),
147 "".to_string(),
148 "## Target Users".to_string(),
149 "- Primary: [user type with specific pain points]".to_string(),
150 "- Secondary: [additional user segments]".to_string(),
151 "".to_string(),
152 "## Value Proposition".to_string(),
153 "[Unique solution approach and competitive advantages]".to_string(),
154 "".to_string(),
155 "## Key Features".to_string(),
156 "1. [Core feature with user benefit]".to_string(),
157 "2. [Secondary feature with business value]".to_string(),
158 "3. [Future capability or integration]".to_string(),
159 "".to_string(),
160 "# TECH STACK TEMPLATE (150+ chars):".to_string(),
161 "".to_string(),
162 "## Backend".to_string(),
163 "- **Language**: Rust 1.70+ (performance, safety)".to_string(),
164 "- **Framework**: Tokio async runtime (concurrency)".to_string(),
165 "- **Database**: PostgreSQL 14+ (ACID compliance, JSON support)".to_string(),
166 "".to_string(),
167 "## Frontend".to_string(),
168 "- **Framework**: React 18 with TypeScript (type safety)".to_string(),
169 "- **State**: Redux Toolkit (predictable state management)".to_string(),
170 "".to_string(),
171 "## Deployment".to_string(),
172 "- **Platform**: AWS ECS (container orchestration)".to_string(),
173 "- **CI/CD**: GitHub Actions (automated testing/deployment)".to_string(),
174 "".to_string(),
175 "## Rationale".to_string(),
176 "[Brief explanation of technology choices and constraints]".to_string(),
177 "".to_string(),
178 "# SPECIFICATION TEMPLATE (200+ chars):".to_string(),
179 "".to_string(),
180 "# [Feature Name]".to_string(),
181 "".to_string(),
182 "## Overview".to_string(),
183 "[Feature description, purpose, and context within the system]".to_string(),
184 "".to_string(),
185 "## Requirements".to_string(),
186 "".to_string(),
187 "### Functional Requirements".to_string(),
188 "- FR1: [Specific functional requirement]".to_string(),
189 "- FR2: [Another functional requirement]".to_string(),
190 "".to_string(),
191 "### Non-Functional Requirements".to_string(),
192 "- Performance: [specific performance criteria]".to_string(),
193 "- Security: [security requirements and constraints]".to_string(),
194 "".to_string(),
195 "## Acceptance Criteria".to_string(),
196 "1. **Given** [context], **When** [action], **Then** [expected result]".to_string(),
197 "2. **Given** [context], **When** [action], **Then** [expected result]".to_string(),
198 "".to_string(),
199 "## Implementation Approach".to_string(),
200 "".to_string(),
201 "### Architecture".to_string(),
202 "[High-level approach and component interaction]".to_string(),
203 "".to_string(),
204 "### API Design".to_string(),
205 "```http".to_string(),
206 "POST /api/endpoint".to_string(),
207 "Content-Type: application/json".to_string(),
208 "".to_string(),
209 "{".to_string(),
210 " \"param\": \"value\"".to_string(),
211 "}".to_string(),
212 "```".to_string(),
213 "".to_string(),
214 "### Database Changes".to_string(),
215 "[Schema modifications, migrations, indexes]".to_string(),
216 "".to_string(),
217 "## Testing Strategy".to_string(),
218 "- Unit tests: [specific test coverage]".to_string(),
219 "- Integration tests: [component interaction testing]".to_string(),
220 "- E2E tests: [user workflow validation]".to_string(),
221 "".to_string(),
222 "# NOTES TEMPLATE (50+ chars):".to_string(),
223 "".to_string(),
224 "## Design Decisions".to_string(),
225 "- **Choice**: [decision made]".to_string(),
226 "- **Rationale**: [why this approach]".to_string(),
227 "- **Alternatives**: [other options considered]".to_string(),
228 "".to_string(),
229 "## Dependencies".to_string(),
230 "- [External system or feature dependency]".to_string(),
231 "- [Library or service requirement]".to_string(),
232 "".to_string(),
233 "## Implementation Notes".to_string(),
234 "- [Technical consideration or constraint]".to_string(),
235 "- [Performance or security consideration]".to_string(),
236 "".to_string(),
237 "## Future Enhancements".to_string(),
238 "- [Potential improvement or extension]".to_string(),
239 "- [Scalability consideration]".to_string(),
240 "".to_string(),
241 "# TASK LIST TEMPLATE (100+ chars):".to_string(),
242 "".to_string(),
243 "## Phase 1: Setup and Architecture".to_string(),
244 "- [ ] Create database schema and migrations".to_string(),
245 "- [ ] Set up API endpoint structure".to_string(),
246 "- [ ] Implement core data models".to_string(),
247 "- [ ] Write unit tests for models".to_string(),
248 "".to_string(),
249 "## Phase 2: Core Implementation".to_string(),
250 "- [ ] Implement business logic layer".to_string(),
251 "- [ ] Add input validation and error handling".to_string(),
252 "- [ ] Create API endpoints with proper responses".to_string(),
253 "- [ ] Write integration tests for API".to_string(),
254 "".to_string(),
255 "## Phase 3: Frontend Integration".to_string(),
256 "- [ ] Create UI components".to_string(),
257 "- [ ] Implement state management".to_string(),
258 "- [ ] Add form validation and user feedback".to_string(),
259 "- [ ] Write E2E tests for user workflows".to_string(),
260 "".to_string(),
261 "## Phase 4: Testing and Deployment".to_string(),
262 "- [ ] Performance testing and optimization".to_string(),
263 "- [ ] Security review and fixes".to_string(),
264 "- [ ] Documentation updates".to_string(),
265 "- [ ] Production deployment and monitoring".to_string(),
266 "".to_string(),
267 "# CONTENT QUALITY GUIDELINES".to_string(),
268 "".to_string(),
269 "## Writing Style:".to_string(),
270 "- Use present tense and active voice".to_string(),
271 "- Be specific and measurable".to_string(),
272 "- Include concrete examples".to_string(),
273 "- Write for both humans and LLMs".to_string(),
274 "".to_string(),
275 "## Technical Depth:".to_string(),
276 "- Include version numbers for dependencies".to_string(),
277 "- Reference specific files, functions, or endpoints".to_string(),
278 "- Provide code examples for complex concepts".to_string(),
279 "- Link to external documentation where relevant".to_string(),
280 "".to_string(),
281 "## Structure Requirements:".to_string(),
282 "- Use consistent header hierarchy".to_string(),
283 "- Group related content under clear sections".to_string(),
284 "- Include both high-level overview and specific details".to_string(),
285 "- End with actionable next steps or success criteria".to_string(),
286 ],
287 workflow_guide: vec![
288 "ALWAYS use proper markdown formatting for structure and readability".to_string(),
289 "Length requirements: Vision ≥200 chars, Tech-stack ≥150 chars, Summary ≥100 chars, Specs ≥200 chars".to_string(),
290 "Use ## headers for major sections, ### for subsections in all content types".to_string(),
291 "Include code blocks with language specifications for technical examples".to_string(),
292 "Use bullet points for features/requirements, numbered lists for sequential steps".to_string(),
293 "Task lists must use - [ ] format for checkboxes to enable progress tracking".to_string(),
294 "Include specific examples, version numbers, and concrete implementation details".to_string(),
295 "Write in present tense with active voice for clarity and consistency".to_string(),
296 "Reference external documentation with proper links where applicable".to_string(),
297 "Use 'foundry validate_content' to verify formatting and content quality".to_string(),
298 ],
299 }
300}
301
302fn create_project_structure_help() -> HelpContent {
303 HelpContent {
304 title: "Foundry Project Structure".to_string(),
305 description: "Understanding the file organization and directory structure that Foundry creates and manages.".to_string(),
306 examples: vec![
307 "~/.foundry/PROJECT_NAME/".to_string(),
308 "├── vision.md # High-level product vision and roadmap".to_string(),
309 "├── tech-stack.md # Technology choices and architecture decisions".to_string(),
310 "├── summary.md # Concise summary for quick context loading".to_string(),
311 "└── specs/".to_string(),
312 " ├── 20250823_143052_user_auth/".to_string(),
313 " │ ├── spec.md # Feature specification and requirements".to_string(),
314 " │ ├── task-list.md # Implementation checklist (updated by agents)".to_string(),
315 " │ └── notes.md # Additional context and design decisions".to_string(),
316 " └── 20250824_091234_api_endpoints/".to_string(),
317 " ├── spec.md".to_string(),
318 " ├── task-list.md".to_string(),
319 " └── notes.md".to_string(),
320 ],
321 workflow_guide: vec![
322 "All files use markdown format for consistent rendering across tools".to_string(),
323 "Spec directories use ISO timestamp format: YYYYMMDD_HHMMSS_feature_name".to_string(),
324 "Feature names must use snake_case (e.g., user_auth, api_endpoints)".to_string(),
325 "Project files provide context for LLM sessions".to_string(),
326 "Spec files contain feature-specific implementation guidance".to_string(),
327 "Task-list.md serves as living checklist - update as work progresses".to_string(),
328 "Notes.md captures design decisions and context for future reference".to_string(),
329 ],
330 }
331}
332
333fn create_parameter_guidance_help() -> HelpContent {
334 HelpContent {
335 title: "Parameter Guidelines and Schemas".to_string(),
336 description: "Detailed guidance on parameter requirements, formats, and validation rules for all Foundry commands.".to_string(),
337 examples: vec![
338 "# create_project parameters:".to_string(),
339 "project_name: kebab-case identifier (e.g., my-awesome-project)".to_string(),
340 "vision: High-level product vision (≥200 chars, 2-4 paragraphs)".to_string(),
341 "tech_stack: Technology decisions with rationale (≥150 chars)".to_string(),
342 "summary: Concise vision+tech summary (≥100 chars)".to_string(),
343 "".to_string(),
344 "# create_spec parameters:".to_string(),
345 "project_name: kebab-case project identifier".to_string(),
346 "feature_name: snake_case identifier (e.g., user_auth)".to_string(),
347 "spec: Detailed requirements and implementation approach".to_string(),
348 "notes: Design decisions, dependencies, considerations".to_string(),
349 "tasks: Implementation checklist in markdown list format".to_string(),
350 "".to_string(),
351 "# validate_content parameters:".to_string(),
352 "content_type: vision|tech-stack|summary|spec|notes".to_string(),
353 "content: Content to validate against type-specific rules".to_string(),
354 "".to_string(),
355 "# Common validation rules:".to_string(),
356 "- Project names: kebab-case (my-awesome-project)".to_string(),
357 "- Feature names: snake_case (user_authentication)".to_string(),
358 "- Content: Non-empty, minimum length requirements".to_string(),
359 "- Markdown: Valid markdown formatting encouraged".to_string(),
360 ],
361 workflow_guide: vec![
362 "All content parameters are REQUIRED - Foundry never generates content".to_string(),
363 "Use specific, descriptive project and feature names".to_string(),
364 "Validate content before creation to catch issues early".to_string(),
365 "Minimum content lengths ensure sufficient detail for LLM context".to_string(),
366 "Rich parameter descriptions guide LLM content creation".to_string(),
367 "Error messages provide actionable guidance for parameter fixes".to_string(),
368 ],
369 }
370}
371
372fn create_decision_points_help() -> HelpContent {
373 HelpContent {
374 title: "Decision Points and Tool Selection".to_string(),
375 description: "Guidance for choosing the right Foundry tools based on user intent and context. Emphasizes user-driven decisions over automated sequences.".to_string(),
376 examples: vec![
377 "# Decision: User wants to start a project".to_string(),
378 "Questions to ask:".to_string(),
379 "- Do they have existing code to analyze? → analyze_project".to_string(),
380 "- Are they starting from scratch? → create_project".to_string(),
381 "- Do they have vision/tech-stack content ready? → Wait for content".to_string(),
382 "".to_string(),
383 "# Decision: User mentions a feature or functionality".to_string(),
384 "Questions to ask:".to_string(),
385 "- Have they described the feature requirements? → create_spec".to_string(),
386 "- Do they need to think through the requirements first? → Ask for details".to_string(),
387 "- Is there an existing project for this feature? → Check with list_projects".to_string(),
388 "".to_string(),
389 "# Decision: User wants to continue work".to_string(),
390 "Questions to ask:".to_string(),
391 "- Do they know which project? → load_project with project_name".to_string(),
392 "- Do they want to see all projects? → list_projects".to_string(),
393 "- Do they want to work on a specific feature? → load_spec with project_name and spec_name".to_string(),
394 "".to_string(),
395 "# Decision: User's intent is unclear".to_string(),
396 "Clarifying questions to ask:".to_string(),
397 "- 'What would you like to work on?'".to_string(),
398 "- 'Are you starting something new or continuing existing work?'".to_string(),
399 "- 'Do you have a specific feature in mind?'".to_string(),
400 ],
401 workflow_guide: vec![
402 "Never assume user intent - always ask clarifying questions".to_string(),
403 "Provide options based on context, not directive commands".to_string(),
404 "Wait for user to provide content before using creation tools".to_string(),
405 "Use conditional language: 'If you want X, then Y tool helps'".to_string(),
406 "Guide decision-making, don't make decisions for the user".to_string(),
407 "Tool selection should always follow user intent, not prescribed workflows".to_string(),
408 ],
409 }
410}
411
412fn create_tool_capabilities_help() -> HelpContent {
413 HelpContent {
414 title: "Tool Capabilities and Appropriate Usage".to_string(),
415 description: "Understanding when each Foundry tool is appropriate and what user input is required for effective usage.".to_string(),
416 examples: vec![
417 "# create_project - When appropriate:".to_string(),
418 "- User wants to start a new project from scratch".to_string(),
419 "- User has provided vision, tech-stack, and summary content".to_string(),
420 "- User input required: Complete content for all three sections".to_string(),
421 "- Don't use without: User-provided content for vision/tech-stack/summary".to_string(),
422 "".to_string(),
423 "# analyze_project - When appropriate:".to_string(),
424 "- User wants to create project structure for existing codebase".to_string(),
425 "- LLM has analyzed codebase using analysis tools".to_string(),
426 "- User input required: LLM-generated analysis-based content".to_string(),
427 "- Don't use without: Thorough codebase analysis first".to_string(),
428 "".to_string(),
429 "# create_spec - When appropriate:".to_string(),
430 "- User has described a specific feature they want to implement".to_string(),
431 "- User has provided requirements or functionality details".to_string(),
432 "- User input required: Feature description, requirements, implementation approach".to_string(),
433 "- Don't use without: User-provided feature requirements and details".to_string(),
434 "".to_string(),
435 "# load_project - When appropriate:".to_string(),
436 "- User wants to continue work on an existing project".to_string(),
437 "- User has specified which project they want to work with".to_string(),
438 "- User input required: Project name".to_string(),
439 "- Don't use without: Clear user intent to work on specific project".to_string(),
440 "".to_string(),
441 "# load_spec - When appropriate:".to_string(),
442 "- User wants to work on a specific feature".to_string(),
443 "- User has mentioned a particular spec or feature name".to_string(),
444 "- User input required: Project name, optionally spec name".to_string(),
445 "- Don't use without: User intent to work on specific feature".to_string(),
446 "".to_string(),
447 "# validate_content - When appropriate:".to_string(),
448 "- User wants to check content quality before creating projects/specs".to_string(),
449 "- LLM wants to verify content meets requirements".to_string(),
450 "- User input required: Content to validate and content type".to_string(),
451 "- Don't use without: Actual content to validate".to_string(),
452 ],
453 workflow_guide: vec![
454 "Every tool requires specific user input - never proceed without it".to_string(),
455 "Tool appropriateness depends on user intent, not prescribed sequences".to_string(),
456 "Wait for user to express clear intent before suggesting tools".to_string(),
457 "Ask clarifying questions when user intent doesn't match tool capabilities".to_string(),
458 "Provide tool options based on what user wants to accomplish".to_string(),
459 "Remember: tools support user goals, they don't drive the workflow".to_string(),
460 ],
461 }
462}
463
464fn create_edit_commands_help() -> HelpContent {
465 HelpContent {
466 title: "Edit Commands for Deterministic Spec Updates".to_string(),
467 description: "Use update_spec with a 'commands' array to perform precise, idempotent edits "
468 .to_string()
469 + "with minimal parameters. Supported commands: set_task_status, upsert_task, "
470 + "append_to_section. Selectors: task_text (exact task text), section (header text, "
471 + "case-insensitive).",
472 examples: vec![
473 "# Mark a task done".to_string(),
474 ("{\"name\": \"update_spec\", \"arguments\": {".to_string()
475 + "\"project_name\": \"proj\", "
476 + "\"spec_name\": \"20250917_auth\", "
477 + "\"commands\": [{\"target\": \"tasks\", \"command\": \"set_task_status\", "
478 + "\"selector\": {\"type\": \"task_text\", \"value\": \"Implement OAuth2 integration\"}, "
479 + "\"status\": \"done\"}]}}"),
480 "".to_string(),
481 "# Upsert a task (no duplicates)".to_string(),
482 ("{\"name\": \"update_spec\", \"arguments\": {".to_string()
483 + "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
484 + "\"commands\": [{\"target\": \"tasks\", \"command\": \"upsert_task\", "
485 + "\"selector\": {\"type\": \"task_text\", \"value\": \"Add password validation\"}, "
486 + "\"content\": \"- [ ] Add password validation\"}]}}"),
487 "".to_string(),
488 "# Append to a section in spec.md".to_string(),
489 ("{\"name\": \"update_spec\", \"arguments\": {".to_string()
490 + "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
491 + "\"commands\": [{\"target\": \"spec\", \"command\": \"append_to_section\", "
492 + "\"selector\": {\"type\": \"section\", \"value\": \"## Requirements\"}, "
493 + "\"content\": \"- Two-factor authentication support\"}]}}"),
494 ],
495 workflow_guide: vec![
496 "Always load current content before editing; copy exact task text and section headers"
497 .to_string(),
498 "append_to_section is valid only for spec and notes (not tasks)".to_string(),
499 "Idempotent behavior: re-sending same commands is safe".to_string(),
500 "On ambiguity or no match, the tool returns candidate suggestions; re-issue with "
501 .to_string()
502 + "suggested selector",
503 ],
504 }
505}