use crate::cli::args::GetFoundryHelpArgs;
use crate::types::responses::{
FoundryResponse, GetFoundryHelpResponse, HelpContent, ValidationStatus,
};
use anyhow::Result;
pub async fn execute(args: GetFoundryHelpArgs) -> Result<FoundryResponse<GetFoundryHelpResponse>> {
let topic = args.topic.as_deref().unwrap_or("overview");
let content = match topic {
"workflows" => create_workflows_help(),
"decision-points" => create_decision_points_help(),
"content-examples" => create_content_examples_help(),
"project-structure" => create_project_structure_help(),
"parameter-guidance" => create_parameter_guidance_help(),
"tool-capabilities" => create_tool_capabilities_help(),
"edit-commands" => create_edit_commands_help(),
_ => create_overview_help(),
};
let next_steps = vec![
"Available help topics: workflows, decision-points, content-examples, project-structure, parameter-guidance, tool-capabilities, edit-commands".to_string(),
"Choose topics based on what you need guidance for".to_string(),
"Use decision-points topic to understand when each tool is appropriate".to_string(),
"Use edit-commands topic for deterministic, idempotent spec edits with examples".to_string(),
];
let workflow_hints = vec![
"Help topics provide user-driven decision support, not automated sequences".to_string(),
"All commands return JSON for programmatic consumption".to_string(),
"Content must be provided by LLMs as arguments - Foundry manages structure only"
.to_string(),
"Always wait for user intent before suggesting tools".to_string(),
];
Ok(FoundryResponse {
data: GetFoundryHelpResponse {
topic: topic.to_string(),
content,
},
next_steps,
validation_status: ValidationStatus::Complete,
workflow_hints,
})
}
pub fn create_overview_help() -> HelpContent {
HelpContent {
title: "Foundry - Project Management for AI Coding Assistants".to_string(),
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(),
examples: vec![
"{\"name\": \"create_project\", \"arguments\": {\"project_name\": \"my-app\", \"vision\": \"...\", \"tech_stack\": \"...\", \"summary\": \"...\"}}".to_string(),
"{\"name\": \"load_project\", \"arguments\": {\"project_name\": \"my-app\"}} # Load complete project context".to_string(),
"{\"name\": \"create_spec\", \"arguments\": {\"project_name\": \"my-app\", \"feature_name\": \"user_auth\", \"spec\": \"...\", \"notes\": \"...\", \"tasks\": \"...\"}}".to_string(),
"{\"name\": \"list_projects\", \"arguments\": {}} # Discover available projects".to_string(),
],
workflow_guide: vec![
"Tools available based on user intent - no fixed sequences".to_string(),
"Use get_foundry_help with decision-points topic for guidance on tool selection".to_string(),
"All content (vision, specs, notes) must be provided by LLMs".to_string(),
"Foundry creates structured file organization for consistent context".to_string(),
"Always wait for user to express intent before suggesting next tools".to_string(),
],
}
}
pub fn create_workflows_help() -> HelpContent {
HelpContent {
title: "User-Driven Foundry Usage Patterns".to_string(),
description: "Guidance for using Foundry tools based on user intent and project context, emphasizing user-driven decisions rather than automated sequences.".to_string(),
examples: vec![
"# When user expresses intent to start a new project:".to_string(),
"→ Ask user to provide vision, tech-stack, and summary content".to_string(),
"→ Use: {\"name\": \"create_project\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"vision\": \"...\", \"tech_stack\": \"...\", \"summary\": \"...\"}}".to_string(),
"→ Wait for user to express what they want to work on next".to_string(),
"".to_string(),
"# When user wants to work with existing codebase:".to_string(),
"→ Use analysis tools (codebase_search, grep_search, read_file) to understand code".to_string(),
"→ Create project structure based on your analysis findings".to_string(),
"→ Use: {\"name\": \"analyze_project\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"vision\": \"...\", \"tech_stack\": \"...\", \"summary\": \"...\"}}".to_string(),
"".to_string(),
"# When user mentions a specific feature to implement:".to_string(),
"→ Ask user to describe feature requirements and approach".to_string(),
"→ Use: {\"name\": \"create_spec\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"feature_name\": \"FEATURE_NAME\", \"spec\": \"...\", \"notes\": \"...\", \"tasks\": \"...\"}}".to_string(),
"→ Let user guide implementation approach".to_string(),
"".to_string(),
"# When user wants to continue previous work:".to_string(),
"→ Use: {\"name\": \"list_projects\", \"arguments\": {}} to show available options".to_string(),
"→ Use: {\"name\": \"load_project\", \"arguments\": {\"project_name\": \"PROJECT_NAME\"}} to get project context".to_string(),
"→ Ask user what they want to work on specifically".to_string(),
"".to_string(),
"# When user wants to make targeted updates to existing specs:".to_string(),
"→ Use: {\"name\": \"load_spec\", \"arguments\": {\"project_name\": \"PROJECT_NAME\", \"spec_name\": \"SPEC_NAME\"}} to see current content".to_string(),
"→ For small targeted changes (mark task complete, add single item, append to a section): use update_spec with edit commands".to_string(),
"→ Commands available: set_task_status, upsert_task, append_to_section".to_string(),
],
workflow_guide: vec![
"Always wait for user intent before suggesting tools".to_string(),
"Provide options and capabilities, not directive sequences".to_string(),
"Always provide complete content in arguments - never expect Foundry to generate content".to_string(),
"Use validate_content to check content quality before creating projects/specs".to_string(),
"Ask clarifying questions when user intent is unclear".to_string(),
"Let users drive the workflow - tools support user goals".to_string(),
"For targeted updates, use edit commands with precise selectors (task_text, section)".to_string(),
"Always load current content before editing; copy exact task text and headers".to_string(),
],
}
}
pub fn create_content_examples_help() -> HelpContent {
HelpContent {
title: "Content Examples and Markdown Formatting Guidelines".to_string(),
description: "Comprehensive formatting standards, content templates, and markdown structure guidelines for all foundry content types.".to_string(),
examples: vec![
"# MARKDOWN FORMATTING STANDARDS".to_string(),
"".to_string(),
"## Header Hierarchy:".to_string(),
"# Main Document Title (for specs only)".to_string(),
"## Major Sections (Problem, Requirements, Implementation)".to_string(),
"### Subsections (API Design, Database Schema, Error Handling)".to_string(),
"#### Minor Details (specific implementation notes)".to_string(),
"".to_string(),
"## Lists and Structure:".to_string(),
"- Use bullet points for features, requirements, considerations".to_string(),
"1. Use numbered lists for sequential steps or priorities".to_string(),
"- [ ] Use checkboxes for task lists (uncompleted)".to_string(),
"- [x] Use checked boxes for completed tasks".to_string(),
"".to_string(),
"## Code and Technical Content:".to_string(),
"```rust".to_string(),
"// Use language-specific code blocks".to_string(),
"fn example() { }".to_string(),
"```".to_string(),
"`inline code` for variables, commands, or short snippets".to_string(),
"".to_string(),
"## Tables for Complex Information:".to_string(),
"| API Endpoint | Method | Purpose |".to_string(),
"| ------------ | ------ | ------- |".to_string(),
"| /api/users | GET | List users |".to_string(),
"".to_string(),
"# VISION CONTENT TEMPLATE (200+ chars):".to_string(),
"".to_string(),
"## Problem".to_string(),
"[Specific problem statement with context and impact]".to_string(),
"".to_string(),
"## Target Users".to_string(),
"- Primary: [user type with specific pain points]".to_string(),
"- Secondary: [additional user segments]".to_string(),
"".to_string(),
"## Value Proposition".to_string(),
"[Unique solution approach and competitive advantages]".to_string(),
"".to_string(),
"## Key Features".to_string(),
"1. [Core feature with user benefit]".to_string(),
"2. [Secondary feature with business value]".to_string(),
"3. [Future capability or integration]".to_string(),
"".to_string(),
"# TECH STACK TEMPLATE (150+ chars):".to_string(),
"".to_string(),
"## Backend".to_string(),
"- **Language**: Rust 1.70+ (performance, safety)".to_string(),
"- **Framework**: Tokio async runtime (concurrency)".to_string(),
"- **Database**: PostgreSQL 14+ (ACID compliance, JSON support)".to_string(),
"".to_string(),
"## Frontend".to_string(),
"- **Framework**: React 18 with TypeScript (type safety)".to_string(),
"- **State**: Redux Toolkit (predictable state management)".to_string(),
"".to_string(),
"## Deployment".to_string(),
"- **Platform**: AWS ECS (container orchestration)".to_string(),
"- **CI/CD**: GitHub Actions (automated testing/deployment)".to_string(),
"".to_string(),
"## Rationale".to_string(),
"[Brief explanation of technology choices and constraints]".to_string(),
"".to_string(),
"# SPECIFICATION TEMPLATE (200+ chars):".to_string(),
"".to_string(),
"# [Feature Name]".to_string(),
"".to_string(),
"## Overview".to_string(),
"[Feature description, purpose, and context within the system]".to_string(),
"".to_string(),
"## Requirements".to_string(),
"".to_string(),
"### Functional Requirements".to_string(),
"- FR1: [Specific functional requirement]".to_string(),
"- FR2: [Another functional requirement]".to_string(),
"".to_string(),
"### Non-Functional Requirements".to_string(),
"- Performance: [specific performance criteria]".to_string(),
"- Security: [security requirements and constraints]".to_string(),
"".to_string(),
"## Acceptance Criteria".to_string(),
"1. **Given** [context], **When** [action], **Then** [expected result]".to_string(),
"2. **Given** [context], **When** [action], **Then** [expected result]".to_string(),
"".to_string(),
"## Implementation Approach".to_string(),
"".to_string(),
"### Architecture".to_string(),
"[High-level approach and component interaction]".to_string(),
"".to_string(),
"### API Design".to_string(),
"```http".to_string(),
"POST /api/endpoint".to_string(),
"Content-Type: application/json".to_string(),
"".to_string(),
"{".to_string(),
" \"param\": \"value\"".to_string(),
"}".to_string(),
"```".to_string(),
"".to_string(),
"### Database Changes".to_string(),
"[Schema modifications, migrations, indexes]".to_string(),
"".to_string(),
"## Testing Strategy".to_string(),
"- Unit tests: [specific test coverage]".to_string(),
"- Integration tests: [component interaction testing]".to_string(),
"- E2E tests: [user workflow validation]".to_string(),
"".to_string(),
"# NOTES TEMPLATE (50+ chars):".to_string(),
"".to_string(),
"## Design Decisions".to_string(),
"- **Choice**: [decision made]".to_string(),
"- **Rationale**: [why this approach]".to_string(),
"- **Alternatives**: [other options considered]".to_string(),
"".to_string(),
"## Dependencies".to_string(),
"- [External system or feature dependency]".to_string(),
"- [Library or service requirement]".to_string(),
"".to_string(),
"## Implementation Notes".to_string(),
"- [Technical consideration or constraint]".to_string(),
"- [Performance or security consideration]".to_string(),
"".to_string(),
"## Future Enhancements".to_string(),
"- [Potential improvement or extension]".to_string(),
"- [Scalability consideration]".to_string(),
"".to_string(),
"# TASK LIST TEMPLATE (100+ chars):".to_string(),
"".to_string(),
"## Phase 1: Setup and Architecture".to_string(),
"- [ ] Create database schema and migrations".to_string(),
"- [ ] Set up API endpoint structure".to_string(),
"- [ ] Implement core data models".to_string(),
"- [ ] Write unit tests for models".to_string(),
"".to_string(),
"## Phase 2: Core Implementation".to_string(),
"- [ ] Implement business logic layer".to_string(),
"- [ ] Add input validation and error handling".to_string(),
"- [ ] Create API endpoints with proper responses".to_string(),
"- [ ] Write integration tests for API".to_string(),
"".to_string(),
"## Phase 3: Frontend Integration".to_string(),
"- [ ] Create UI components".to_string(),
"- [ ] Implement state management".to_string(),
"- [ ] Add form validation and user feedback".to_string(),
"- [ ] Write E2E tests for user workflows".to_string(),
"".to_string(),
"## Phase 4: Testing and Deployment".to_string(),
"- [ ] Performance testing and optimization".to_string(),
"- [ ] Security review and fixes".to_string(),
"- [ ] Documentation updates".to_string(),
"- [ ] Production deployment and monitoring".to_string(),
"".to_string(),
"# CONTENT QUALITY GUIDELINES".to_string(),
"".to_string(),
"## Writing Style:".to_string(),
"- Use present tense and active voice".to_string(),
"- Be specific and measurable".to_string(),
"- Include concrete examples".to_string(),
"- Write for both humans and LLMs".to_string(),
"".to_string(),
"## Technical Depth:".to_string(),
"- Include version numbers for dependencies".to_string(),
"- Reference specific files, functions, or endpoints".to_string(),
"- Provide code examples for complex concepts".to_string(),
"- Link to external documentation where relevant".to_string(),
"".to_string(),
"## Structure Requirements:".to_string(),
"- Use consistent header hierarchy".to_string(),
"- Group related content under clear sections".to_string(),
"- Include both high-level overview and specific details".to_string(),
"- End with actionable next steps or success criteria".to_string(),
],
workflow_guide: vec![
"ALWAYS use proper markdown formatting for structure and readability".to_string(),
"Length requirements: Vision ≥200 chars, Tech-stack ≥150 chars, Summary ≥100 chars, Specs ≥200 chars".to_string(),
"Use ## headers for major sections, ### for subsections in all content types".to_string(),
"Include code blocks with language specifications for technical examples".to_string(),
"Use bullet points for features/requirements, numbered lists for sequential steps".to_string(),
"Task lists must use - [ ] format for checkboxes to enable progress tracking".to_string(),
"Include specific examples, version numbers, and concrete implementation details".to_string(),
"Write in present tense with active voice for clarity and consistency".to_string(),
"Reference external documentation with proper links where applicable".to_string(),
"Use 'mcp_foundry_validate_content' to verify formatting and content quality".to_string(),
],
}
}
pub fn create_project_structure_help() -> HelpContent {
HelpContent {
title: "Foundry Project Structure".to_string(),
description: "Understanding the file organization and directory structure that Foundry creates and manages.".to_string(),
examples: vec![
"~/.foundry/PROJECT_NAME/".to_string(),
"├── vision.md # High-level product vision and roadmap".to_string(),
"├── tech-stack.md # Technology choices and architecture decisions".to_string(),
"├── summary.md # Concise summary for quick context loading".to_string(),
"└── specs/".to_string(),
" ├── 20250823_143052_user_auth/".to_string(),
" │ ├── spec.md # Feature specification and requirements".to_string(),
" │ ├── task-list.md # Implementation checklist (updated by agents)".to_string(),
" │ └── notes.md # Additional context and design decisions".to_string(),
" └── 20250824_091234_api_endpoints/".to_string(),
" ├── spec.md".to_string(),
" ├── task-list.md".to_string(),
" └── notes.md".to_string(),
],
workflow_guide: vec![
"All files use markdown format for consistent rendering across tools".to_string(),
"Spec directories use ISO timestamp format: YYYYMMDD_HHMMSS_feature_name".to_string(),
"Feature names must use snake_case (e.g., user_auth, api_endpoints)".to_string(),
"Project files provide context for LLM sessions".to_string(),
"Spec files contain feature-specific implementation guidance".to_string(),
"Task-list.md serves as living checklist - update as work progresses".to_string(),
"Notes.md captures design decisions and context for future reference".to_string(),
],
}
}
pub fn create_parameter_guidance_help() -> HelpContent {
HelpContent {
title: "Parameter Guidelines and Schemas".to_string(),
description: "Detailed guidance on parameter requirements, formats, and validation rules for all Foundry commands.".to_string(),
examples: vec![
"# create_project parameters:".to_string(),
"project_name: kebab-case identifier (e.g., my-awesome-project)".to_string(),
"vision: High-level product vision (≥200 chars, 2-4 paragraphs)".to_string(),
"tech_stack: Technology decisions with rationale (≥150 chars)".to_string(),
"summary: Concise vision+tech summary (≥100 chars)".to_string(),
"".to_string(),
"# create_spec parameters:".to_string(),
"project_name: kebab-case project identifier".to_string(),
"feature_name: snake_case identifier (e.g., user_auth)".to_string(),
"spec: Detailed requirements and implementation approach".to_string(),
"notes: Design decisions, dependencies, considerations".to_string(),
"tasks: Implementation checklist in markdown list format".to_string(),
"".to_string(),
"# validate_content parameters:".to_string(),
"content_type: vision|tech-stack|summary|spec|notes".to_string(),
"content: Content to validate against type-specific rules".to_string(),
"".to_string(),
"# Common validation rules:".to_string(),
"- Project names: kebab-case (my-awesome-project)".to_string(),
"- Feature names: snake_case (user_authentication)".to_string(),
"- Content: Non-empty, minimum length requirements".to_string(),
"- Markdown: Valid markdown formatting encouraged".to_string(),
],
workflow_guide: vec![
"All content parameters are REQUIRED - Foundry never generates content".to_string(),
"Use specific, descriptive project and feature names".to_string(),
"Validate content before creation to catch issues early".to_string(),
"Minimum content lengths ensure sufficient detail for LLM context".to_string(),
"Rich parameter descriptions guide LLM content creation".to_string(),
"Error messages provide actionable guidance for parameter fixes".to_string(),
],
}
}
pub fn create_decision_points_help() -> HelpContent {
HelpContent {
title: "Decision Points and Tool Selection".to_string(),
description: "Guidance for choosing the right Foundry tools based on user intent and context. Emphasizes user-driven decisions over automated sequences.".to_string(),
examples: vec![
"# Decision: User wants to start a project".to_string(),
"Questions to ask:".to_string(),
"- Do they have existing code to analyze? → analyze_project".to_string(),
"- Are they starting from scratch? → create_project".to_string(),
"- Do they have vision/tech-stack content ready? → Wait for content".to_string(),
"".to_string(),
"# Decision: User mentions a feature or functionality".to_string(),
"Questions to ask:".to_string(),
"- Have they described the feature requirements? → create_spec".to_string(),
"- Do they need to think through the requirements first? → Ask for details".to_string(),
"- Is there an existing project for this feature? → Check with list_projects".to_string(),
"".to_string(),
"# Decision: User wants to continue work".to_string(),
"Questions to ask:".to_string(),
"- Do they know which project? → load_project with project_name".to_string(),
"- Do they want to see all projects? → list_projects".to_string(),
"- Do they want to work on a specific feature? → load_spec with project_name and spec_name".to_string(),
"".to_string(),
"# Decision: User's intent is unclear".to_string(),
"Clarifying questions to ask:".to_string(),
"- 'What would you like to work on?'".to_string(),
"- 'Are you starting something new or continuing existing work?'".to_string(),
"- 'Do you have a specific feature in mind?'".to_string(),
],
workflow_guide: vec![
"Never assume user intent - always ask clarifying questions".to_string(),
"Provide options based on context, not directive commands".to_string(),
"Wait for user to provide content before using creation tools".to_string(),
"Use conditional language: 'If you want X, then Y tool helps'".to_string(),
"Guide decision-making, don't make decisions for the user".to_string(),
"Tool selection should always follow user intent, not prescribed workflows".to_string(),
],
}
}
pub fn create_tool_capabilities_help() -> HelpContent {
HelpContent {
title: "Tool Capabilities and Appropriate Usage".to_string(),
description: "Understanding when each Foundry tool is appropriate and what user input is required for effective usage.".to_string(),
examples: vec![
"# create_project - When appropriate:".to_string(),
"- User wants to start a new project from scratch".to_string(),
"- User has provided vision, tech-stack, and summary content".to_string(),
"- User input required: Complete content for all three sections".to_string(),
"- Don't use without: User-provided content for vision/tech-stack/summary".to_string(),
"".to_string(),
"# analyze_project - When appropriate:".to_string(),
"- User wants to create project structure for existing codebase".to_string(),
"- LLM has analyzed codebase using analysis tools".to_string(),
"- User input required: LLM-generated analysis-based content".to_string(),
"- Don't use without: Thorough codebase analysis first".to_string(),
"".to_string(),
"# create_spec - When appropriate:".to_string(),
"- User has described a specific feature they want to implement".to_string(),
"- User has provided requirements or functionality details".to_string(),
"- User input required: Feature description, requirements, implementation approach".to_string(),
"- Don't use without: User-provided feature requirements and details".to_string(),
"".to_string(),
"# load_project - When appropriate:".to_string(),
"- User wants to continue work on an existing project".to_string(),
"- User has specified which project they want to work with".to_string(),
"- User input required: Project name".to_string(),
"- Don't use without: Clear user intent to work on specific project".to_string(),
"".to_string(),
"# load_spec - When appropriate:".to_string(),
"- User wants to work on a specific feature".to_string(),
"- User has mentioned a particular spec or feature name".to_string(),
"- User input required: Project name, optionally spec name".to_string(),
"- Don't use without: User intent to work on specific feature".to_string(),
"".to_string(),
"# validate_content - When appropriate:".to_string(),
"- User wants to check content quality before creating projects/specs".to_string(),
"- LLM wants to verify content meets requirements".to_string(),
"- User input required: Content to validate and content type".to_string(),
"- Don't use without: Actual content to validate".to_string(),
],
workflow_guide: vec![
"Every tool requires specific user input - never proceed without it".to_string(),
"Tool appropriateness depends on user intent, not prescribed sequences".to_string(),
"Wait for user to express clear intent before suggesting tools".to_string(),
"Ask clarifying questions when user intent doesn't match tool capabilities".to_string(),
"Provide tool options based on what user wants to accomplish".to_string(),
"Remember: tools support user goals, they don't drive the workflow".to_string(),
],
}
}
pub fn create_edit_commands_help() -> HelpContent {
HelpContent {
title: "Edit Commands for Deterministic Spec Updates".to_string(),
description: "Use update_spec with a 'commands' array to perform comprehensive content management "
.to_string()
+ "with precise targeting and idempotent updates. Each command requires: target (spec|tasks|notes), "
+ "command (set_task_status|upsert_task|append_to_section|remove_list_item|remove_from_section|remove_section|replace_list_item|replace_in_section|replace_section_content), "
+ "selector (section|task_text|text_in_section), and required fields (status for set_task_status, content for others).",
examples: vec![
"# TASK MANAGEMENT COMMANDS".to_string(),
"".to_string(),
"# Mark task as completed (requires status field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", "
+ "\"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"tasks\", \"command\": \"set_task_status\", "
+ "\"selector\": {\"type\": \"task_text\", \"value\": \"Implement OAuth2 integration\"}, "
+ "\"status\": \"done\"}]}}"),
"".to_string(),
"# Mark task as incomplete (requires status field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", "
+ "\"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"tasks\", \"command\": \"set_task_status\", "
+ "\"selector\": {\"type\": \"task_text\", \"value\": \"Setup database schema\"}, "
+ "\"status\": \"todo\"}]}}"),
"".to_string(),
"# Add new task (requires content field, prevents duplicates)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"tasks\", \"command\": \"upsert_task\", "
+ "\"selector\": {\"type\": \"task_text\", \"value\": \"Add password validation\"}, "
+ "\"content\": \"- [ ] Add password validation\"}]}}"),
"".to_string(),
"# CONTENT ADDITION COMMANDS".to_string(),
"".to_string(),
"# Append to spec.md section (requires content field, spec/notes only)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"spec\", \"command\": \"append_to_section\", "
+ "\"selector\": {\"type\": \"section\", \"value\": \"## Requirements\"}, "
+ "\"content\": \"- Two-factor authentication support\"}]}}"),
"".to_string(),
"# Append to notes.md section (requires content field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"notes\", \"command\": \"append_to_section\", "
+ "\"selector\": {\"type\": \"section\", \"value\": \"## Implementation Notes\"}, "
+ "\"content\": \"Authentication will use JWT tokens with 15-minute expiration\"}]}}"),
"".to_string(),
"# CONTENT REMOVAL COMMANDS".to_string(),
"".to_string(),
"# Remove task from task list".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"tasks\", \"command\": \"remove_list_item\", "
+ "\"selector\": {\"type\": \"task_text\", \"value\": \"Outdated task\"}}]}}"),
"".to_string(),
"# Remove content from section (requires content field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"spec\", \"command\": \"remove_from_section\", "
+ "\"selector\": {\"type\": \"section\", \"value\": \"## Requirements\"}, "
+ "\"content\": \"- Legacy requirement to remove\"}]}}"),
"".to_string(),
"# Remove entire section".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"spec\", \"command\": \"remove_section\", "
+ "\"selector\": {\"type\": \"section\", \"value\": \"## Deprecated Section\"}}]}}"),
"".to_string(),
"# CONTENT REPLACEMENT COMMANDS".to_string(),
"".to_string(),
"# Replace task content (requires content field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"tasks\", \"command\": \"replace_list_item\", "
+ "\"selector\": {\"type\": \"task_text\", \"value\": \"Basic auth\"}, "
+ "\"content\": \"- [ ] Implement JWT-based authentication with refresh tokens\"}]}}"),
"".to_string(),
"# Replace text within section (requires content field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"spec\", \"command\": \"replace_in_section\", "
+ "\"selector\": {\"type\": \"text_in_section\", \"section\": \"## Requirements\", \"text\": \"MySQL 5.7\"}, "
+ "\"content\": \"MySQL 8.0\"}]}}"),
"".to_string(),
"# Replace entire section content (requires content field)".to_string(),
("{\"name\": \"update_spec\", \"arguments\": {".to_string()
+ "\"project_name\": \"proj\", \"spec_name\": \"20250917_auth\", "
+ "\"commands\": [{\"target\": \"spec\", \"command\": \"replace_section_content\", "
+ "\"selector\": {\"type\": \"section\", \"value\": \"## Implementation Approach\"}, "
+ "\"content\": \"Complete new implementation approach\\n\\n- Step 1\\n- Step 2\"}]}}"),
"".to_string(),
"# SELECTOR TYPES REFERENCE".to_string(),
"".to_string(),
"# section: Case-insensitive header matching (## Requirements)".to_string(),
"# task_text: Normalized task text (ignores checkbox, whitespace, periods)".to_string(),
"# text_in_section: Precise text within specific section".to_string(),
"".to_string(),
"# COMMAND RESTRICTIONS".to_string(),
"".to_string(),
"# set_task_status: tasks target only, requires status field".to_string(),
"# upsert_task: tasks target only, requires content field".to_string(),
"# append_to_section: spec/notes targets only, requires content field".to_string(),
"# remove_list_item: any target, no additional fields".to_string(),
"# remove_from_section: spec/notes targets only, requires content field".to_string(),
"# remove_section: spec/notes targets only, no additional fields".to_string(),
"# replace_list_item: any target, requires content field".to_string(),
"# replace_in_section: spec/notes targets only, requires content field".to_string(),
"# replace_section_content: spec/notes targets only, requires content field".to_string(),
],
workflow_guide: vec![
"CRITICAL: Always load current content before editing; copy exact task text and section headers"
.to_string(),
"Required fields: set_task_status needs 'status' field, all others need 'content' field"
.to_string(),
"Target restrictions: Task commands (set_task_status, upsert_task) only work with 'tasks' target"
.to_string(),
"Target restrictions: append_to_section is invalid for 'tasks' target - use upsert_task instead"
.to_string(),
"Selector precision: task_text normalizes text (ignores checkbox, whitespace, periods)"
.to_string(),
"Selector precision: section headers are case-insensitive but must include hashes (## Requirements)"
.to_string(),
"Idempotent behavior: re-sending same commands is safe and reports skipped/idempotent"
.to_string(),
"Error recovery: On ambiguity or no match, tool returns candidate suggestions with exact text to use"
.to_string(),
"Batch operations: Single update_spec call can execute multiple commands atomically"
.to_string(),
],
}
}