### Setup Development Environment

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Clones the spec-server repository and installs development dependencies.

```bash
git clone https://github.com/teknologika/spec-server.git
cd spec-server
pip install -e ".[dev]"
```

--------------------------------

### Verify spec-server Installation

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Checks if spec-server is installed by listing installed packages and searching for 'spec-server'. Also demonstrates how to run spec-server using the module execution.

```bash
pip list | grep spec-server
```

```bash
python -m spec_server
```

--------------------------------

### Install/Upgrade spec-server

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Installs or upgrades the spec-server package, including all necessary dependencies, or installs from source with development dependencies.

```bash
pip install --upgrade spec-server
```

```bash
pip install -e ".[dev]"
```

--------------------------------

### LLM Interaction Examples

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

Examples of prompts to guide LLM interactions for iteration, providing rationale, and highlighting trade-offs in a development context.

```text
Remember that we can iterate on these [requirements/design/tasks] as needed. It's better to get feedback early rather than proceeding with incorrect assumptions.
```

```text
I'm suggesting this [requirement/design approach/task breakdown] because [rationale]. This helps address [specific need or concern you mentioned].
```

```text
There's a trade-off to consider here:
- Option A offers [benefit] but has [drawback]
- Option B offers [benefit] but has [drawback]

What's more important for your specific needs?
```

--------------------------------

### Install spec-server

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Provides instructions for installing the spec-server package, both from PyPI and from source.

```bash
pip install spec-server
```

```bash
git clone https://github.com/teknologika/spec-server.git
cd spec-server
pip install -e .
```

--------------------------------

### Force Reinstall spec-server

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Reinstalls spec-server forcefully, ensuring that any corrupted installations are overwritten and entry points are correctly set up.

```bash
pip install --force-reinstall spec-server
```

--------------------------------

### Configuration File Example

Source: https://github.com/teknologika/spec-server/blob/main/README.md

An example of the optional `spec-server.json` file for configuring various aspects of the spec-server.

```json
{
  "specs_dir": "specs",
  "auto_detect_workspace": true,
  "workspace_specs_dir": ".specs",
  "host": "127.0.0.1",
  "port": 8000,
  "transport": "stdio",
  "log_level": "INFO",
  "auto_backup": true,
  "cache_enabled": true
}
```

--------------------------------

### Manage PATH for Scripts

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Finds the user base directory where pip installs scripts and demonstrates how to add this directory to the system's PATH environment variable.

```bash
# Find where pip installs scripts
python -m site --user-base
# Add to PATH if needed
export PATH="$PATH:$(python -m site --user-base)/bin"
```

--------------------------------

### File System and Backup Configuration

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Details environment variables and commands related to file system access and backup configuration for the spec-server.

```APIDOC
File System & Backup Configuration:
  - `SPEC_SERVER_SPECS_DIR`: Path to the specs directory (default: ./specs).
    - Example: `export SPEC_SERVER_SPECS_DIR=/data/specs`
  - `SPEC_SERVER_AUTO_BACKUP`: Boolean to enable/disable automatic backups (default: true).
    - Example: `export SPEC_SERVER_AUTO_BACKUP=false`
  - Directory Permissions:
    - Specs directory: `chmod 755 specs`
    - Backups directory: `chmod 755 backups`
```

--------------------------------

### Connect Back to Requirements Example

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

Demonstrates how to connect a design decision back to a specific project requirement, explaining the benefit of the decision.

```plaintext
This design decision directly supports the requirement you mentioned about [specific requirement]. It ensures that [benefit].
```

--------------------------------

### Test Server Startup and Basic Functionality

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Provides commands to test the spec-server's basic operations, including its help output and the ability to respond to a simple JSON-RPC ping request.

```bash
# Test server startup
spec-server --help

# Test with simple command
echo '{"jsonrpc": "2.0", "method": "ping", "id": 1}' | spec-server
```

--------------------------------

### Leverage Automatic Features Example

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

Shows how a system can automatically format tasks and link them to requirements, moving irrelevant content to appropriate documents.

```plaintext
I'll create the tasks now, and the system will automatically format them and link them to the relevant requirements we discussed. If any content doesn't belong in tasks, it will be moved to the appropriate document.
```

--------------------------------

### Check Directory Permissions

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Checks and sets read/write/execute permissions for the 'specs' directory, ensuring spec-server can create files and directories.

```bash
ls -la specs/
chmod 755 specs/
```

--------------------------------

### Acknowledge Uncertainty Example

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

Provides an example of how to acknowledge uncertainty about a specific aspect and request further information for informed decision-making.

```plaintext
I'm not entirely certain about [aspect]. Could you provide more information about [specific question] so we can make a more informed decision?
```

--------------------------------

### Automatic Design Enhancement Example

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

Explains how a system automatically enhances designs with the Intent/Goals/Logic format for consistent documentation structure.

```plaintext
The system will automatically enhance this design with the Intent/Goals/Logic format for any technical elements that need it. This ensures consistent documentation structure across all your specs.
```

--------------------------------

### Verify spec-server Status (Stdio and SSE)

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Tests if the spec-server is running and responsive using the stdio transport by sending an initialize request, and checks the SSE endpoint.

```bash
# For stdio transport
echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1}' | spec-server

# For SSE transport
curl http://localhost:8000/sse
```

--------------------------------

### Test Specific Functionality (Get Config)

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

A Python snippet to test a specific piece of functionality, in this case, retrieving the server's configuration. This is useful for isolating and testing individual components.

```python
from spec_server.config import get_config; print(get_config())
```

--------------------------------

### Logging Configuration

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Specifies environment variables for configuring the logging level and output file for the spec-server.

```APIDOC
Logging Configuration:
  - `SPEC_SERVER_LOG_LEVEL`: Sets the logging verbosity (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).
    - Default: INFO
    - Example: `export SPEC_SERVER_LOG_LEVEL=DEBUG`
  - `SPEC_SERVER_LOG_FILE`: Specifies the path to the log file.
    - Default: stdout
    - Example: `export SPEC_SERVER_LOG_FILE=debug.log`
```

--------------------------------

### Create and Secure Specs Directory

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Ensures the 'specs' directory exists and has appropriate permissions for the spec-server to operate correctly. This is crucial for organizing and accessing specification files.

```bash
mkdir -p specs
chmod 755 specs
```

--------------------------------

### Call Tool with Correct Parameters

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Demonstrates the correct Python syntax for calling a spec-server tool, specifically 'create_spec', with properly formatted parameters like feature name (kebab-case) and initial idea.

```python
# Correct format
await session.call_tool("create_spec", {
    "feature_name": "user-auth",  # kebab-case
    "initial_idea": "User authentication system"
})
```

--------------------------------

### Common Error Codes and Descriptions

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

A reference table mapping common error codes encountered in the spec-server to their descriptions and potential causes.

```APIDOC
Common Error Codes:
  - `SPEC_NOT_FOUND`: Specification not found. Causes: Typo in feature name, spec not created.
  - `SPEC_ALREADY_EXISTS`: Specification already exists. Causes: Duplicate creation attempt.
  - `SPEC_INVALID_NAME`: Invalid feature name format. Causes: Not kebab-case, contains special characters.
  - `DOCUMENT_NOT_FOUND`: Document not found. Causes: Invalid document type, spec not created.
  - `VALIDATION_ERROR`: Input validation failed. Causes: Invalid parameters, format issues.
  - `WORKFLOW_APPROVAL_REQUIRED`: Phase approval needed. Causes: Missing `phase_approval=true`.
  - `TASK_NOT_FOUND`: Task not found. Causes: Invalid task identifier.
  - `FILE_NOT_FOUND`: File reference not found. Causes: Broken file reference.
  - `INTERNAL_ERROR`: Unexpected server error. Causes: System issue, check logs.
```

--------------------------------

### Use Enhanced Design Format Example

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

Illustrates structuring a component's documentation using the Intent/Goals/Logic format, emphasizing clarity and communication of purpose and implementation.

```plaintext
For this component, let me structure it using the Intent/Goals/Logic format:

**Intent**: This component serves as the main data processor for user requests.

**Goals**:
- Validate incoming data according to business rules
- Transform data into the required internal format
- Handle errors gracefully with meaningful messages
- Maintain high performance under load

**Logic**: The component will implement a pipeline pattern where data flows through validation, transformation, and error handling stages. It will use dependency injection for testability and include comprehensive logging for debugging.

Does this structure clearly communicate the component's purpose and implementation approach?
```

--------------------------------

### Check Python Version

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Verifies the installed Python version to ensure compatibility with spec-server, which requires Python 3.12 or later.

```bash
python3 --version
```

--------------------------------

### Requirements Phase - Understand User Needs

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet provides guiding questions for an LLM to understand user needs during the requirements phase of the spec-server workflow.

```text
Before we document requirements, let's discuss:
- Who will use this feature?
- What problem does it solve?
- What are the must-have vs. nice-to-have aspects?
- How will we know if it's successful?
```

--------------------------------

### Change SSE Port

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Starts the spec-server SSE transport on a different port to avoid conflicts if the default port (e.g., 8000) is already in use.

```bash
spec-server sse --port 8001
```

--------------------------------

### Performance and Memory Configuration

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Outlines environment variables used to configure performance-related settings such as caching and validation strictness, as well as memory management options.

```APIDOC
Performance & Memory Configuration:
  - `SPEC_SERVER_CACHE_ENABLED`: Boolean to enable/disable caching (default: false).
    - Example: `export SPEC_SERVER_CACHE_ENABLED=true`
  - `SPEC_SERVER_CACHE_SIZE`: Maximum cache size in MB (default: 100).
    - Example: `export SPEC_SERVER_CACHE_SIZE=200`
  - `SPEC_SERVER_STRICT_VALIDATION`: Boolean to enforce strict validation (default: true).
    - Example: `export SPEC_SERVER_STRICT_VALIDATION=false`
  - `SPEC_SERVER_MAX_SPECS`: Maximum number of specs to manage (default: 500).
    - Example: `export SPEC_SERVER_MAX_SPECS=100`
```

--------------------------------

### Create and Secure Backup Directory

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Ensures the 'backups' directory exists and has the correct permissions for storing backup files. This is essential for successful backup operations.

```bash
mkdir -p backups
chmod 755 backups
```

--------------------------------

### Check Port Usage

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Lists network connections and listening ports to identify which processes are using a specific port.

```bash
netstat -tulpn | grep :8000
```

--------------------------------

### Run Unit Tests

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Executes the project's unit tests using the pytest framework. Running tests is a fundamental step in verifying code correctness and identifying regressions.

```bash
python -m pytest tests/ -v
```

--------------------------------

### Find and Kill Process by Port

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Identifies the process ID (PID) using a specific port (e.g., 8000) and terminates it.

```bash
lsof -i :8000
kill -9 <PID>
```

--------------------------------

### Collect System and Package Information

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Gathers essential system and package information, including OS details, Python versions, and specific package versions. This data is vital for diagnosing environment-related issues.

```bash
# System info
uname -a
python3 --version
pip --version

# Package versions
pip list | grep -E "(spec-server|fastmcp|pydantic)"

# Environment
env | grep SPEC_SERVER

# File permissions
ls -la specs/ backups/
```

--------------------------------

### Basic MCP Client Configuration

Source: https://github.com/teknologika/spec-server/blob/main/docs/mcp-client-config.md

Configures the MCP client to connect to spec-server using the 'stdio' transport. This is the default and simplest setup.

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["stdio"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

--------------------------------

### Configure Custom Specs Directory

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Sets the SPEC_SERVER_SPECS_DIR environment variable to a custom, writable directory for storing specs, or configures it within MCP settings.

```bash
export SPEC_SERVER_SPECS_DIR=~/my-specs
```

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["stdio"],
      "env": {
        "SPEC_SERVER_SPECS_DIR": "/path/to/writable/directory/specs"
      }
    }
  }
}
```

--------------------------------

### Configure spec-server Transport and Logging

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Configures the spec-server transport (stdio) and enables debug logging by setting the SPEC_SERVER_LOG_LEVEL environment variable within the MCP configuration.

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["stdio"],
      "env": {
        "SPEC_SERVER_LOG_LEVEL": "DEBUG"
      }
    }
  }
}
```

--------------------------------

### Requirements Phase - Discuss Acceptance Criteria (EARS)

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet guides an LLM on discussing acceptance criteria using the EARS (Event-driven, Actor-centric, Rule-based, State-based) format.

```text
Let's define some acceptance criteria using the EARS format. These are specific conditions that must be met for the feature to be considered complete:
- WHEN [condition] THEN the system SHALL [response]
- WHEN [condition] THEN the system SHALL [response]
- IF [condition] THEN the system SHALL [response]
```

--------------------------------

### Disable Automatic Backups

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Temporarily disables the automatic backup feature by setting an environment variable. This can be useful for troubleshooting backup-related issues or during maintenance.

```bash
export SPEC_SERVER_AUTO_BACKUP=false
spec-server
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Configures the spec-server to output detailed debug information to a specified log file. This is essential for diagnosing complex issues and understanding the server's internal state.

```bash
# Environment variable
export SPEC_SERVER_LOG_LEVEL=DEBUG
export SPEC_SERVER_LOG_FILE=debug.log
spec-server

# Check logs
tail -f debug.log
```

--------------------------------

### Configure Custom Specs Directory

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Allows users to specify a custom location for the specs directory using an environment variable. This is useful for managing specs in non-default locations.

```bash
export SPEC_SERVER_SPECS_DIR=/path/to/specs
spec-server
```

--------------------------------

### Handle Tool Execution Errors

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Shows how to check the result of a tool call in Python, specifically looking for a 'success' flag and extracting error messages and suggestions if the operation failed.

```python
result = await session.call_tool("create_spec", {...})
if not result.get("success", True):
    print("Error:", result.get("message"))
    print("Suggestions:", result.get("suggestions", []))
```

--------------------------------

### Check System Resources (CPU and Disk)

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Commands to monitor system resource utilization, including CPU load and disk space. High resource usage can lead to slow response times and performance degradation.

```bash
top
df -h
```

--------------------------------

### Limit Maximum Number of Specs

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Sets a limit on the maximum number of specifications the server will manage. This can help control memory usage and prevent excessive resource consumption.

```bash
export SPEC_SERVER_MAX_SPECS=100
```

--------------------------------

### Content Validation Rules

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Defines the rules for content validation, including maximum size limits and restrictions on dangerous content types like script tags or executable code.

```APIDOC
Content Validation:
  - Maximum Size: 1MB (1,000,000 bytes)
  - Minimum for ideas: 10 characters
  - Forbidden Content:
    - <script> tags
    - JavaScript URLs (e.g., javascript:void(0))
    - Executable content
```

--------------------------------

### Reduce Validation Strictness

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Disables strict validation rules for content. This can improve performance by reducing the overhead of thorough validation, but may allow less rigorously checked content.

```bash
export SPEC_SERVER_STRICT_VALIDATION=false
```

--------------------------------

### Enable Caching and Set Cache Size

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Configures the spec-server to use caching for performance improvements and sets the maximum size of the cache. Adjusting cache size can help manage memory usage.

```bash
export SPEC_SERVER_CACHE_ENABLED=true
export SPEC_SERVER_CACHE_SIZE=200
```

--------------------------------

### Monitor Process Memory Usage

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Displays information about running processes, including memory usage. This command helps identify which processes are consuming the most memory, aiding in diagnosing memory issues.

```bash
ps aux | grep spec-server
```

--------------------------------

### Check Disk Space Usage

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

A utility command to check available disk space on the current file system. This helps diagnose issues related to insufficient storage, which can impact server operations.

```bash
df -h .
```

--------------------------------

### Reduce Cache Size for Memory Management

Source: https://github.com/teknologika/spec-server/blob/main/docs/troubleshooting.md

Decreases the maximum size of the cache to reduce the server's memory footprint. This is a common strategy for mitigating high memory consumption issues.

```bash
export SPEC_SERVER_CACHE_SIZE=50
```

--------------------------------

### Run spec-server from Command Line

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Demonstrates how to run the spec-server using different transport methods (stdio and SSE) and ports.

```bash
# Run with stdio transport (default)
spec-server

# Run with SSE transport on port 8000
spec-server sse 8000

# Run with SSE transport on custom port
spec-server sse 3000
```

--------------------------------

### Initial Engagement - Explain Benefits

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet outlines the benefits of using the spec-server workflow, which an LLM can use to explain the value proposition to the user.

```text
This approach will help us:
- Clearly define what success looks like
- Make thoughtful design decisions
- Create a clear implementation plan
- Avoid rework and scope creep
```

--------------------------------

### Design Phase - Explore Alternatives

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet provides a template for an LLM to present and discuss alternative design approaches with the user.

```text
I see a few possible approaches to implementing this:
1. [Approach A] which offers [benefits] but has [drawbacks]
2. [Approach B] which offers [benefits] but has [drawbacks]

What are your thoughts on these approaches?
```

--------------------------------

### Initial Engagement - Introduce spec-server Workflow

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet provides the initial conversational prompt for an LLM to introduce the spec-server workflow to a user when they express interest in building a feature.

```text
I see you want to build [feature]. Let's use a structured approach to define requirements, design the solution, and break it down into implementation tasks. This will help ensure we build exactly what you need.
```

--------------------------------

### Run Tests

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Executes the test suite for the spec-server project.

```bash
pytest
```

--------------------------------

### spec-server LLM Guidance System

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Explains how to access and utilize the LLM guidance system within spec-server for effective usage, including enhanced design format and auto-format task lists.

```APIDOC
Accessing Guidance:
  For AI Assistants:
    - Use get_full_guidance() to access the complete guidance document
    - Use get_guidance(phase="requirements|design|tasks") for phase-specific guidance
    - Guidance includes conversation starters, templates, and best practices
  For Developers:
    - Guidance is available at [docs/llm-guidance.md](docs/llm-guidance.md)
    - Automatically accessible through MCP tools when using spec-server
    - Always up-to-date with the installed version

Enhanced Features:
  Enhanced Design Format:
    - All technical elements use Intent/Goals/Logic structure
    - Intent: Brief description of purpose
    - Goals: Specific, measurable objectives
    - Logic: Detailed implementation approach

  Auto-Format Task Lists:
    - Tasks are automatically formatted into consistent structure
    - Requirements references are automatically added
    - Non-task content is moved to appropriate documents
    - Task completion is validated against requirements and design
```

--------------------------------

### Environment Variables

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Lists the available environment variables for configuring spec-server behavior.

```bash
- SPEC_SERVER_SPECS_DIR: Base directory for specs (default: "specs")
- SPEC_SERVER_AUTO_DETECT_WORKSPACE: Enable workspace detection (default: "true")
- SPEC_SERVER_WORKSPACE_SPECS_DIR: Specs directory name in workspace (default: ".specs")
- SPEC_SERVER_PORT: Default SSE server port (default: 8000)
- SPEC_SERVER_LOG_LEVEL: Logging level (default: "INFO")
```

--------------------------------

### Requirements Phase - Summarize Understanding

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet provides a template for an LLM to summarize its understanding of user requirements and seek confirmation.

```text
Based on our discussion, here's my understanding of what you need... [summary]
Is this accurate? Would you like to add or modify anything?
```

--------------------------------

### Code Quality Tools

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Commands for formatting, sorting imports, linting, and type checking the project code.

```bash
# Format code
black src tests

# Sort imports
isort src tests

# Lint code
flake8 src tests

# Type checking
mypy src
```

--------------------------------

### Configure spec-server in MCP Client

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Shows how to add spec-server as an MCP server in a client configuration file.

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["stdio"],
      "disabled": false
    }
  }
}
```

--------------------------------

### Tasks Phase - Identify Potential Challenges

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet provides prompts for an LLM to identify and discuss potential implementation challenges with the user.

```text
I see a few areas that might be challenging:
- [Challenge 1] which we could address by...
- [Challenge 2] which we could address by...

Are there other challenges you anticipate?
```

--------------------------------

### Requirements Document Template

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

A template for creating requirements documents, including sections for introduction, requirements with user stories, and acceptance criteria using the EARS format.

```markdown
# Requirements Document

## Introduction
[Brief description of the feature and its purpose]

## Requirements

### Requirement 1

**User Story:** As a [user type], I want to [action], so that [benefit] 

#### Acceptance Criteria

1. WHEN [condition] THEN the system SHALL [response]
2. WHEN [condition] THEN the system SHALL [response]
3. WHEN [condition] THEN the system SHALL [response]
4. WHEN [condition] THEN the system SHALL [response]

### Requirement 2

**User Story:** As a [user type], I want to [action], so that [benefit] 

#### Acceptance Criteria

1. WHEN [condition] THEN the system SHALL [response]
2. WHEN [condition] THEN the system SHALL [response]
3. WHEN [condition] THEN the system SHALL [response]

### Requirement 3

**User Story:** As a [user type], I want to [action], so that [benefit] 

#### Acceptance Criteria

1. WHEN [condition] THEN the system SHALL [response]
2. WHEN [condition] THEN the system SHALL [response]

**Important Numbering System:**
- **Requirements**: Numbered sequentially (1, 2, 3, etc.)
- **Acceptance Criteria**: Numbered within each requirement (1, 2, 3, etc.)
- **Reference Format**: Tasks reference specific criteria as "1.1, 1.2, 2.1, 3.2" (requirement.criteria)
- **EARS Format**: Use "WHEN [condition] THEN system SHALL [response]" for acceptance criteria
```

--------------------------------

### Workspace Integration Configuration

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Environment variables to control workspace detection and the naming of the specs directory.

```bash
# Enable/disable workspace detection (default: true)
export SPEC_SERVER_AUTO_DETECT_WORKSPACE=true

# Customize specs directory name in workspace (default: ".specs")
export SPEC_SERVER_WORKSPACE_SPECS_DIR=".my-specs"

# Customize fallback directory name (default: "specs")
export SPEC_SERVER_SPECS_DIR="my-specs"
```

--------------------------------

### Tasks Phase - Discuss Implementation Strategy

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet lists discussion points for an LLM regarding the implementation strategy during the tasks phase.

```text
Now let's talk about how to break down the implementation:
- Should we use a particular development methodology?
- Are there dependencies between components?
- What's the logical sequence for implementation?
- How should we approach testing?
```

--------------------------------

### File References in Specs

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Demonstrates how to reference content from other files within specification documents using the #[[file:path]] syntax.

```markdown
# API Design

The API follows the OpenAPI specification defined in:
#[[file:api/openapi.yaml]]
```

--------------------------------

### spec-server MCP Tools

Source: https://github.com/teknologika/spec-server/blob/main/README.md

Details the available MCP tools provided by the spec-server, including their parameters and functionality.

```APIDOC
create_spec:
  description: Create a new feature specification with initial requirements document.
  parameters:
    feature_name (string): Kebab-case feature identifier
    initial_idea (string): User's rough feature description

update_spec_document:
  description: Update requirements, design, or tasks documents with workflow validation.
  parameters:
    feature_name (string): Target spec identifier
    document_type (enum): "requirements" | "design" | "tasks"
    content (string): Updated document content
    phase_approval (boolean): Whether user approves current phase

list_specs:
  description: List all existing specifications with their current status and progress.

read_spec_document:
  description: Retrieve content of spec documents with file reference resolution.
  parameters:
    feature_name (string): Target spec identifier
    document_type (enum): "requirements" | "design" | "tasks"

execute_task:
  description: Execute a specific implementation task from the tasks document.
  parameters:
    feature_name (string): Target spec identifier
    task_identifier (string): Task number/identifier

delete_spec:
  description: Remove a specification entirely including all documents.
  parameters:
    feature_name (string): Target spec identifier

get_full_guidance:
  description: Get the complete LLM guidance document for effective spec-server usage.
  returns: Complete guidance on conversational approach, enhanced design format, and auto-format task lists.

get_guidance:
  description: Get phase-specific guidance for requirements, design, or tasks phases.
  parameters:
    phase (string): "requirements" | "design" | "tasks" | "general"
  returns: Phase-specific conversation starters, templates, and best practices.
```

--------------------------------

### Requirements Phase - Structure Requirements

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet explains the structured referencing system for requirements and acceptance criteria used in the spec-server workflow.

```text
I'll organize these into numbered requirements with numbered acceptance criteria. This creates a clear reference system where:
- Requirement 1 has acceptance criteria 1.1, 1.2, 1.3, etc.
- Requirement 2 has acceptance criteria 2.1, 2.2, 2.3, etc.
- Tasks can then reference specific criteria like "1.1, 2.3, 3.1"
```

--------------------------------

### Tasks Phase - Discuss Testing Approach

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet outlines discussion points for an LLM regarding the testing approach during the tasks phase.

```text
Let's consider how we'll test this feature:
- What unit tests will be needed?
- How about integration tests?
- Are there specific edge cases to test?
```

--------------------------------

### Tasks Document Template

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

A placeholder for a template for creating task documents.

```markdown
# Tasks Document


```

--------------------------------

### Design Phase - Discuss Design Considerations

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet lists key design considerations an LLM should discuss with the user after requirements are approved.

```text
Now that we have clear requirements, let's discuss how to implement this feature:
- What architecture approach makes sense?
- Are there existing components we can leverage?
- What data structures will we need?
- Are there any performance considerations?
```

--------------------------------

### Design Phase - Discuss Technical Details

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet outlines technical details an LLM should cover during the design phase discussion.

```text
Let's talk about some technical details:
- How will this integrate with the existing system?
- What APIs or interfaces will be needed?
- How will we handle error cases?
- What about security considerations?
```

--------------------------------

### Design Document Template

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

A template for creating design documents, covering overview, architecture, components, interfaces, data models, error handling, and testing strategy.

```markdown
# Design for [Feature Name]

## Overview
[High-level description of the solution architecture and design decisions]

## Architecture
[Overall system architecture and integration points]

## Components and Interfaces

### [Component Name]

**Intent**: [Brief description of what this component does and why it exists]

**Goals**:
- [Specific objective this component achieves]
- [Another objective this component achieves]
- [Additional objectives as needed]

**Logic**: [Detailed explanation of how this component works, its implementation approach, and technical details]

### [Interface Name]

**Intent**: [Brief description of what this interface provides and its purpose]

**Goals**:
- [Specific capability this interface enables]
- [Another capability this interface enables]
- [Additional capabilities as needed]

**Logic**: [Detailed explanation of the interface design, methods, parameters, and usage patterns]

## Data Models

### [Data Model Name]

**Intent**: [Brief description of what this data model represents and its role]

**Goals**:
- [Specific data requirement this model addresses]
- [Another data requirement this model addresses]
- [Additional requirements as needed]

**Logic**: [Detailed explanation of the data structure, relationships, validation rules, and usage patterns]

## Error Handling
[Approach to error handling and recovery]

## Testing Strategy
[Approach to testing the implementation]
```

--------------------------------

### Requirements Phase - Explore Constraints

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet lists potential constraints an LLM should discuss with the user during the requirements gathering phase.

```text
Are there any constraints we should consider?
- Technical limitations
- Timeline considerations
- Integration requirements
- Performance expectations
```

--------------------------------

### MCP Client Configuration with Full Path

Source: https://github.com/teknologika/spec-server/blob/main/docs/mcp-client-config.md

Specifies the full path to the spec-server executable, useful when it's not in the system's PATH, such as within a virtual environment.

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "/path/to/your/venv/bin/spec-server",
      "args": ["stdio"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

--------------------------------

### MCP Client Configuration with Workspace Detection

Source: https://github.com/teknologika/spec-server/blob/main/docs/mcp-client-config.md

Enables automatic workspace detection and specifies a local directory for specs by setting SPEC_SERVER_AUTO_DETECT_WORKSPACE and SPEC_SERVER_WORKSPACE_SPECS_DIR environment variables.

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["stdio"],
      "disabled": false,
      "autoApprove": [],
      "env": {
        "SPEC_SERVER_AUTO_DETECT_WORKSPACE": "true",
        "SPEC_SERVER_WORKSPACE_SPECS_DIR": ".specs"
      }
    }
  }
}
```

--------------------------------

### Design Phase - Validate Design Direction

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet provides a prompt for an LLM to propose and validate a design direction with the user.

```text
Based on our discussion, I recommend [design approach] because [rationale].
Does this align with your thinking?
```

--------------------------------

### Create Spec Function Call

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet demonstrates how to invoke the 'create_spec' function to generate a new feature specification. It includes parameters for the feature name and an initial idea based on discussion.

```XML
<function_calls>
<invoke name="create_spec">
<parameter name="feature_name">feature-name<paramet
er name="feature_name">feature-name</parameter>
<parameter name="initial_idea">Comprehensive description based on discussion</parameter>
</invoke>
</function_calls>
```

--------------------------------

### MCP Client Configuration with Custom Specs Directory

Source: https://github.com/teknologika/spec-server/blob/main/docs/mcp-client-config.md

Configures the MCP client to use a custom directory for storing specifications by setting the SPEC_SERVER_SPECS_DIR environment variable. This is useful for read-only file systems.

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["stdio"],
      "disabled": false,
      "autoApprove": [],
      "env": {
        "SPEC_SERVER_SPECS_DIR": "/path/to/writable/directory/specs"
      }
    }
  }
}
```

--------------------------------

### Approve Requirements Function Call

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet demonstrates how to update the specification document to mark requirements as approved. It calls 'update_spec_document' with the feature name, document type as 'requirements', updated content, and phase approval set to true.

```XML
<function_calls>
<invoke name="update_spec_document">
<parameter name="feature_name">feature-name</parameter>
<parameter name="document_type">requirements</parameter>
<parameter name="content">[Updated content based on feedback]</parameter>
<parameter name="phase_approval">true</parameter>
</invoke>
</function_calls>
```

--------------------------------

### Update Spec Document - Task Creation

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This function call is used to update a specification document by creating or updating tasks. It requires the feature name, document type (set to 'tasks'), the content detailing the tasks, and a boolean indicating phase approval (typically false for task creation before final approval).

```APIDOC
function update_spec_document(
  feature_name: str,
  document_type: str = "tasks",
  content: str,
  phase_approval: bool = false
):
  """Updates a specification document with tasks.

  Args:
    feature_name: The name of the feature.
    document_type: The type of document to update (set to 'tasks').
    content: The content detailing the tasks, including descriptions and sub-tasks.
    phase_approval: Boolean indicating if the phase is approved (usually false for initial task creation).
  """
  pass
```

--------------------------------

### Update Design Document Function Call

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet illustrates the use of 'update_spec_document' for documenting the technical design of a feature. It includes parameters for feature name, document type as 'design', detailed content in Intent/Goals/Logic format, and phase approval set to false.

```XML
<function_calls>
<invoke name="update_spec_document">
<parameter name="feature_name">feature-name</parameter>
<parameter name="document_type">design</parameter>
<parameter name="content">
# Design for [Feature Name]

## Overview
[High-level description of the solution architecture and design decisions]

## Architecture
[Overall system architecture and integration points]

## Components and Interfaces

### [Component Name]

**Intent**: [Brief description of what this component does and why it exists]

**Goals**:
- [Specific objective this component achieves]
- [Another objective this component achieves]
- [Additional objectives as needed]

**Logic**: [Detailed explanation of how this component works, its implementation approach, and technical details]

### [Interface Name]

**Intent**: [Brief description of what this interface provides and its purpose]

**Goals**:
- [Specific capability this interface enables]
- [Another capability this interface enables]
- [Additional capabilities as needed]

**Logic**: [Detailed explanation of the interface design, methods, parameters, and usage patterns]

## Data Models

### [Data Model Name]

**Intent**: [Brief description of what this data model represents and its role]

**Goals**:
- [Specific data requirement this model addresses]
- [Another data requirement this model addresses]
- [Additional requirements as needed]

**Logic**: [Detailed explanation of the data structure, relationships, validation rules, and usage patterns]

## Error Handling
[Approach to error handling and recovery]

## Testing Strategy
[Approach to testing the implementation]
</parameter>
<parameter name="phase_approval">false</parameter>
</invoke>
</function_calls>
```

--------------------------------

### Update Requirements Document Function Call

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This snippet shows the invocation of 'update_spec_document' to document feature requirements. It specifies the feature name, document type as 'requirements', provides the content for the requirements document, and sets phase approval to false.

```XML
<function_calls>
<invoke name="update_spec_document">
<parameter name="feature_name">feature-name</parameter>
<parameter name="document_type">requirements</parameter>
<parameter name="content">
# Requirements Document

## Introduction
[Brief description of the feature and its purpose based on discussion]

## Requirements

### Requirement 1

**User Story:** As a [user type], I want to [action], so that [benefit] 

#### Acceptance Criteria

1. WHEN [condition] THEN the system SHALL [response]
2. WHEN [condition] THEN the system SHALL [response]
3. WHEN [condition] THEN the system SHALL [response]

### Requirement 2

**User Story:** As a [user type], I want to [action], so that [benefit] 

#### Acceptance Criteria

1. WHEN [condition] THEN the system SHALL [response]
2. WHEN [condition] THEN the system SHALL [response]

### Requirement 3

**User Story:** As a [user type], I want to [action], so that [benefit] 

#### Acceptance Criteria

1. WHEN [condition] THEN the system SHALL [response]
2. WHEN [condition] THEN the system SHALL [response]
3. WHEN [condition] THEN the system SHALL [response]
</parameter>
<parameter name="phase_approval">false</parameter>
</invoke>
</function_calls>
```

--------------------------------

### Update Spec Document - Design Approval

Source: https://github.com/teknologika/spec-server/blob/main/docs/llm-guidance.md

This function call is used to update a specification document, specifically marking a design as approved. It requires the feature name, document type (set to 'design'), updated content, and a boolean indicating phase approval.

```APIDOC
function update_spec_document(
  feature_name: str,
  document_type: str = "design",
  content: str,
  phase_approval: bool = true
):
  """Updates a specification document.

  Args:
    feature_name: The name of the feature.
    document_type: The type of document to update (e.g., 'design', 'tasks').
    content: The updated content for the document.
    phase_approval: Boolean indicating if the phase is approved.
  """
  pass
```

--------------------------------

### MCP Client Configuration with SSE Transport

Source: https://github.com/teknologika/spec-server/blob/main/docs/mcp-client-config.md

Configures the MCP client to use Server-Sent Events (SSE) transport to communicate with spec-server on a specified port (e.g., 8000).

```json
{
  "mcpServers": {
    "spec-server": {
      "command": "spec-server",
      "args": ["sse", "8000"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.