1 line
19 KiB
JSON
1 line
19 KiB
JSON
{"repo": "bacoco/aidesigner", "files": {"docs/configuration.md": {"ecde8bef51fd18e0a82b9d2a8fef450b67a6e8ae": {"t": 1785674176.2764516, "n": 13119, "h": "c95e7cbc0ea45837", "c": "# Configuration Guide\n\nComplete configuration reference for aidesigner.\n\n> **Legacy aliases**: Existing `npm run bmad*` scripts continue to work, but new projects should prefer the `aidesigner` commands documented below.\n\n## Table of Contents\n\n- [Environment Variables](#environment-variables)\n- [LLM Provider Configuration](#llm-provider-configuration)\n- [MCP Server Configuration](#mcp-server-configuration)\n- [Codex CLI Configuration](#codex-cli-configuration)\n- [Observability & Logging](#observability--logging)\n- [Advanced Settings](#advanced-settings)\n\n## Environment Variables\n\naidesigner can be configured via environment variables in a `.env` file at your project root:\n\n```bash\n# .env\n\n# LLM Provider (claude or glm)\nLLM_PROVIDER=glm\n\n# API Keys\naidesigner_GLM_API_KEY=sk-... # For GLM (preferred)\nANTHROPIC_API_KEY=sk-ant-... # For Claude\n\n# Optional: Override model\nLLM_MODEL=glm-4-plus # Custom GLM model\n```\n\nLegacy names (`BMAD_*`, `GLM_*`, `ZHIPUAI_*`) continue to work, but new projects should prefer the `aidesigner_*` convention.\n\n## LLM Provider Configuration\n\n### ZhipuAI GLM Provider\n\nEnable GLM (ZhipuAI) for the orchestrator:\n\n#### CLI Flags\n\n```bash\n# Use GLM via flag\nnpx aidesigner start --glm\n\n# Explicit provider specification\nnpx aidesigner start --llm-provider=glm\n```\n\n#### Environment Variables\n\nCreate a `.env` file:\n\n```bash\n# .env - GLM Configuration\n\n# Set provider\nLLM_PROVIDER=glm\n\n# API Key (choose one format)\naidesigner_GLM_API_KEY=sk-... # Preferred\nGLM_API_KEY=sk-... # Legacy alias\nZHIPUAI_API_KEY=sk-... # Legacy alias (Codex CLI)\n\n# Optional: Custom model\nLLM_MODEL=glm-4-plus # Default: glm-4\n\n# Optional: Custom endpoint\naidesigner_GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4/chat/completions\n```\n\n#### Variable Priority\n\nWhen GLM mode is active, variables are resolved in this order:\n\n| Variable | Priority | Description |\n| --------------------------- | -------- | --------------------------------------------- |\n| `aidesigner_GLM_BASE_URL` | 1 | GLM API base URL (preferred) |\n| `BMAD_GLM_BASE_URL` | 2 | GLM API base URL (legacy support) |\n| `GLM_BASE_URL` | 3 | GLM API base URL (standard alias) |\n| `ANTHROPIC_BASE_URL` | 4 | Anthropic base URL (fallback) |\n| `aidesigner_GLM_AUTH_TOKEN` | 1 | GLM authentication token (preferred) |\n| `BMAD_GLM_AUTH_TOKEN` | 2 | GLM authentication token (legacy support) |\n| `GLM_AUTH_TOKEN` | 3 | GLM authentication token (standard alias) |\n| `ANTHROPIC_AUTH_TOKEN` | 4 | Anthropic auth token (fallback) |\n| `aidesigner_GLM_API_KEY` | 1 | GLM API key (preferred) |\n| `BMAD_GLM_API_KEY` | 2 | GLM API key (legacy support) |\n| `GLM_API_KEY` | 3 | GLM API key (standard alias) |\n| `ZHIPUAI_API_KEY` | 4 | GLM API key (legacy Codex alias) |\n| `ANTHROPIC_API_KEY` | 5 | Anthropic API key (fallback when nothing set) |\n\n**Note:** At least one of `*_BASE_URL` or `*_API_KEY` must be set when using GLM mode. Legacy `BMAD_*`, `GLM_*`, and `ZHIPUAI_*` values continue to work, but `aidesigner_*` is now the canonical naming.\n\n#### Custom Endpoints\n\nGLM base URLs can include schemes, ports, and paths:\n\n```bash\n# Full custom endpoint (preferred)\naidesigner_GLM_BASE_URL=https://example.com:7443/custom/base\n# Legacy fallback names such as BMAD_GLM_BASE_URL or GLM_BASE_URL remain supported.\n# aidesigner appends: /api/paas/v4/chat/completions\n\n# Default (if no base URL provided)\n# https://open.bigmodel.cn/api/paas/v4/chat/completions\n```\n\n#### Example Usage\n\n```bash\n# Set GLM provider and credentials (preferred names)\nexport aidesigner_ASSISTANT_PROVIDER=glm\nexport aidesigner_GLM_BASE_URL=https://your-glm-endpoint.com\nexport aidesigner_GLM_API_KEY=your-api-key\n# Legacy BMAD_* and GLM_* variables are still honored for backward compatibility.\n\n# Start aidesigner with GLM routing\nnpm run bmad:claude\n# Output: 🌐 GLM mode active: routing Claude CLI through configured GLM endpoint.\n```\n\nGLM routing works with all three assistant entry points:\n\n- `npx aidesigner start --assistant=claude --glm` - Routes Claude CLI through GLM\n- `npx aidesigner start --assistant=codex --glm` - Routes Codex CLI through GLM\n- `npx aidesigner start --assistant=opencode --glm` - Routes OpenCode CLI through GLM\n\n### Anthropic Provider (Default)\n\nUsing Anthropic's Claude (default behavior):\n\n#### CLI Flags\n\n```bash\n# Use Anthropic (default)\nnpx aidesigner start\nnpx aidesigner start --anthropic\n\n# Explicit provider\nnpx aidesigner start --llm-provider=claude\n```\n\n#### Environment Variables\n\n```bash\n# .env - Anthropic Configuration\n\n# Set provider (optional, this is default)\nLLM_PROVIDER=claude\n\n# API Key (only needed for direct API access)\nANTHROPIC_API_KEY=sk-ant-...\n\n# When using Claude CLI, OpenCode CLI, or Codex CLI,\n# the CLI handles authentication automatically\n```\n\n### Switching Providers\n\nSwitch providers anytime:\n\n```bash\n# Start with GLM\nnpx aidesigner start --glm\n\n# Later, switch to Anthropic\nnpx aidesigner start --anthropic\n\n# Or change .env file\necho \"LLM_PROVIDER=claude\" >> .env\nnpx aidesigner start\n```\n\n**Priority order:**\n\n1. CLI flags (highest priority)\n2. Environment variables from `.env`\n3. Default behavior (Anthropic)\n\n## MCP Server Configuration\n\n### Assistant-Specific Configuration\n\n#### Claude CLI Configuration\n\n**Location:** `.claude/mcp-config.json`\n\n```json\n{\n \"aidesigner\": {\n \"command\": \"npx\",\n \"args\": [\"aidesigner-codex\"],\n \"disabled\": false\n },\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-chrome-devtools\"],\n \"disabled\": true\n },\n \"shadcn\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-shadcn\"],\n \"disabled\": true\n }\n}\n```\n\n#### Codex CLI Configuration\n\n**Location:** `~/.codex/config.toml`\n\n```toml\n[[mcp]]\nid = \"aidesigner\"\ncommand = \"npx\"\nargs = [\"aidesigner-codex\"]\nauto_start = true\n\n[[mcp]]\nid = \"chrome-devtools\"\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-chrome-devtools\"]\nauto_start = false\n\n[[mcp]]\nid = \"shadcn\"\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-shadcn\"]\nauto_start = false\n```\n\n### MCP Environment Configuration\n\nAdd environment variables to MCP server configuration:\n\n**Claude CLI** (`.claude/mcp-config.json`):\n\n```json\n{\n \"aidesigner\": {\n \"command\": \"npx\",\n \"args\": [\"aidesigner-codex\"],\n \"env\": {\n \"CODEX_APPROVAL_MODE\": \"true\",\n \"CODEX_LOG_CONTEXT\": \"{\\\"environment\\\":\\\"production\\\"}\"\n }\n }\n}\n```\n\n**Codex CLI** (`~/.codex/config.toml`):\n\n```toml\n[[mcp]]\nid = \"aidesigner\"\ncommand = \"npx\"\nargs = [\"aidesigner-codex\"]\nauto_start = true\n\n [mcp.env]\n CODEX_APPROVAL_MODE = \"true\"\n CODEX_LOG_CONTEXT = '{\"environment\":\"production\"}'\n```\n\n## Codex CLI Configuration\n\n### Approval Mode\n\nControl which operations require manual approval:\n\n```bash\n# Enable approval mode\nCODEX_APPROVAL_MODE=true\n\n# Specify approved operations (bypass approval)\nCODEX_APPROVED_OPERATIONS=generate_deliverable:prd,execute_quick_lane\n```\n\n**Available operations:**\n\n- `generate_deliverable:prd` - Generate Product Requirements Document\n- `generate_deliverable:architecture` - Generate architecture document\n- `generate_deliverable:story` - Generate user stories\n- `execute_quick_lane` - Run Quick Lane workflow\n- `execute_complex_lane` - Run Complex Lane workflow\n- `transition_phase` - Move to next aidesigner phase\n\n### Model Overrides\n\nOverride LLM routing per development lane:\n\n```bash\n# Quick lane: Fast model for simple tasks\nCODEX_QUICK_MODEL=gpt-4.1-mini\n\n# Complex lane: Powerful model for complex features\nCODEX_COMPLEX_MODEL=claude-3-5-sonnet-20241022\n\n# Governance lane: Specialized model for reviews\nCODEX_GOVERNANCE_MODEL=claude-3-5-sonnet-20241022\n```\n\n### Complete Codex Configuration Example\n\n`~/.codex/config.toml`:\n\n```toml\n[[mcp]]\nid = \"aidesigner-codex\"\ncommand = \"npx\"\nargs = [\"aidesigner-codex\"]\nautostart = true\n\n [mcp.env]\n # Approval settings\n CODEX_APPROVAL_MODE = \"true\"\n CODEX_APPROVED_OPERATIONS = \"generate_deliverable:prd,execute_quick_lane\"\n\n # Model routing per lane\n CODEX_QUICK_MODEL = \"gpt-4.1-mini\"\n CODEX_COMPLEX_MODEL = \"claude-3-5-sonnet-20241022\"\n CODEX_GOVERNANCE_MODEL = \"claude-3-5-sonnet-20241022\"\n\n # Observability\n CODEX_LOG_CONTEXT = '{\"environment\":\"local\",\"team\":\"engineering\"}'\n CODEX_METRICS_STDOUT = \"true\"\n\n # Provider overrides\n CODEX_DEFAULT_PROVIDER = \"anthropic\"\n CODEX_FAST_PROVIDER = \"openai\"\n```\n\nSee [`codex-config.toml.example`](../.dev/config/codex-config.toml.example) for a ready-to-copy configuration.\n\n## Observability & Logging\n\n### Structured Logging\n\naidesigner emits structured JSON logs to `stderr`:\n\n```json\n{\n \"ts\": \"2024-07-16T12:34:56.789Z\",\n \"level\": \"info\",\n \"msg\": \"lane_selection_completed\",\n \"service\": \"aidesigner-codex\",\n \"component\": \"mcp-orchestrator\",\n \"operation\": \"execute_workflow\",\n \"lane\": \"quick\",\n \"confidence\": 0.88,\n \"durationMs\": 142.3,\n \"environment\": \"local\"\n}\n```\n\n### Log Context Enrichment\n\nAdd custom fields to all log entries:\n\n```bash\n# Environment variable\nCODEX_LOG_CONTEXT='{\"environment\":\"production\",\"cluster\":\"us-west-2\",\"team\":\"backend\"}'\n```\n\nAll log entries will include these fields automatically.\n\n### Metrics\n\nEnable metrics output to `stdout`:\n\n```bash\n# Enable metrics\nCODEX_METRICS_STDOUT=true\n```\n\n**Metric events include:**\n\n- Lane selection timing\n- Workflow duration\n- Tool execution time\n- Operation success/failure rates\n\nExample metric:\n\n```json\n{\n \"name\": \"lane_selection_duration\",\n \"value\": 142.3,\n \"type\": \"timing\",\n \"unit\": \"ms\",\n \"attributes\": {\n \"lane\": \"quick\",\n \"confidence\": 0.88,\n \"environment\": \"local\"\n }\n}\n```\n\n### Log Levels\n\nControl logging verbosity:\n\n```bash\n# Set log level (debug, info, warn, error)\nLOG_LEVEL=info\n\n# Disable logging\nLOG_LEVEL=error\n```\n\n## Advanced Settings\n\n### Development Mode\n\nEnable development features:\n\n```bash\n# Enable debug mode\nDEBUG=aidesigner:*\n\n# Verbose logging\nVERBOSE=true\n\n# Disable auto-approval (prompt for everything)\nAUTO_APPROVE=false\n```\n\n### Performance Tuning\n\nAdjust performance-related settings:\n\n```bash\n# Quick lane timeout (milliseconds)\nQUICK_LANE_TIMEOUT=180000 # 3 minutes\n\n# Complex lane timeout (milliseconds)\nCOMPLEX_LANE_TIMEOUT=900000 # 15 minutes\n\n# Lane selection confidence threshold (0.0 - 1.0)\nLANE_CONFIDENCE_THRESHOLD=0.7\n```\n\n### State Management\n\nConfigure project state persistence:\n\n```bash\n# State file location (relative to project root)\naidesigner_STATE_DIR=.aidesigner\n\n# Conversation log location\naidesigner_LOG_FILE=.aidesigner/conversation.log\n\n# Auto-save state after each interaction\nAUTO_SAVE_STATE=true\n```\n\n### MCP Server Lifecycle\n\nControl MCP server behavior:\n\n```bash\n# Server startup timeout (milliseconds)\nMCP_STARTUP_TIMEOUT=5000\n\n# Retry failed operations\nMCP_RETRY_COUNT=3\n\n# Retry delay (milliseconds)\nMCP_RETRY_DELAY=1000\n```\n\n## Configuration Validation\n\nValidate your configuration:\n\n```bash\n# Test MCP server connection\nnpm run mcp:doctor\n\n# Test LLM provider connection\nnpx aidesigner start --test\n\n# Audit security settings\nnpm run mcp:audit\n```\n\n## Example Configurations\n\n### Local Development\n\n```bash\n# .env\nLLM_PROVIDER=anthropic\nLOG_LEVEL=debug\nVERBOSE=true\nAUTO_APPROVE=true\nCODEX_METRICS_STDOUT=true\nCODEX_LOG_CONTEXT='{\"environment\":\"local\"}'\n```\n\n### Production\n\n```bash\n# .env\nLLM_PROVIDER=glm\naidesigner_GLM_API_KEY=sk-...\nLOG_LEVEL=info\nAUTO_APPROVE=false\nCODEX_APPROVAL_MODE=true\nCODEX_LOG_CONTEXT='{\"environment\":\"production\",\"team\":\"engineering\"}'\nCODEX_METRICS_STDOUT=true\n```\n\n### CI/CD\n\n```bash\n# .env\nLLM_PROVIDER=glm\naidesigner_GLM_API_KEY=${CI_GLM_API_KEY}\nLOG_LEVEL=warn\nAUTO_APPROVE=true\nCODEX_APPROVAL_MODE=false\nCODEX_LOG_CONTEXT='{\"environment\":\"ci\",\"pipeline\":\"${CI_PIPELINE_ID}\"}'\n```\n\n## Troubleshooting\n\n### Configuration Not Loading\n\nIf environment variables aren't being read:\n\n1. Verify `.env` file is in project root\n2. Check file permissions: `chmod 600 .env`\n3. Ensure no syntax errors in `.env`\n4. Try explicit export: `export $(cat .env | xargs)`\n\n### Wrong LLM Provider\n\nIf using the wrong provider:\n\n1. Check CLI flag: `npx aidesigner start --glm`\n2. Verify `.env` contents: `cat .env | grep LLM_PROVIDER`\n3. Check priority: CLI flags override environment variables\n\n### MCP Server Connection Issues\n\nIf MCP servers fail to connect:\n\n1. Validate configuration: `npm run mcp:doctor`\n2. Check server paths in config files\n3. Test standalone: `npm run mcp`\n4. Review logs for errors\n\n## Next Steps\n\n- **[Installation Guide](installation-methods.md)** - Installation options\n- **[MCP Management](mcp-management.md)** - Extend with MCP servers\n- **[Examples](examples.md)** - Usage examples\n- **[Architecture](../docs/core-architecture.md)** - System design\n"}}, "lolo/README.md": {"ecde8bef51fd18e0a82b9d2a8fef450b67a6e8ae": {"t": 1785846845.473768, "n": 5329, "h": "cf292dc41ecb086c", "c": "# lolo\n\nWelcome to your AiDesigner project! This project follows the **BMAD-METHOD™** (Breakthrough Method of Agile AI-driven Development) - a universal AI agent framework that orchestrates specialized AI agents through structured workflows.\n\n## 🚀 Quick Start\n\n### 1. Install Dependencies\n\n```bash\nnpm install\n```\n\n### 2. Start Development\n\n```bash\n# Launch Codex CLI for interactive development\nnpm run aidesigner:codex\n\n# Or use Claude chat\nnpm run aidesigner:claude\n```\n\n## 📁 Project Structure\n\n```\nlolo/\n├── docs/ # Generated documentation\n│ ├── prd/ # Product requirements (sharded by PO agent)\n│ ├── architecture/ # System architecture (sharded by PO agent)\n│ ├── stories/ # User stories (created by SM agent)\n│ └── qa/ # QA assessments and gates\n│ ├── assessments/\n│ └── gates/\n├── .aidesigner/ # AiDesigner metadata\n└── .mcp.json # MCP server configuration\n```\n\n## 🎯 BMAD Workflow\n\nThe BMAD methodology follows a structured three-phase workflow:\n\n### Phase 1: Planning (Web UI Recommended)\n\nUse BMAD agents in web-based AI platforms (Gemini, ChatGPT) for comprehensive planning:\n\n1. **Analyst Agent** → Creates project brief and market research\n2. **PM Agent** → Generates `docs/prd.md` (Product Requirements Document)\n3. **Architect Agent** → Creates `docs/architecture.md` (System Architecture)\n4. **UX Expert Agent** (optional) → Frontend specifications\n5. **PO Agent** → Validates and \"shards\" documents into subdirectories\n\n### Phase 2: Transition to IDE\n\nCopy generated documents to your project:\n\n- `docs/prd.md` → sharded into `docs/prd/epic-*.md`\n- `docs/architecture.md` → sharded into `docs/architecture/`\n\n### Phase 3: Development (IDE)\n\nUse agents in your IDE (VS Code, Cursor, Claude Code) for implementation:\n\n1. **Scrum Master (SM)** → Creates detailed stories in `docs/stories/`\n2. **Dev Agent** → Implements features following architecture\n3. **QA Agent** → Reviews and validates code quality\n4. **Repeat** until epic is complete\n\n## 🤖 Available Agents\n\nBMAD provides specialized agents for different tasks:\n\n- **Analyst**: Market research, requirements gathering, brainstorming\n- **PM (Product Manager)**: PRD generation, epic/story breakdown\n- **Architect**: Technical architecture, design decisions\n- **UX Expert**: Frontend specs, UI/UX design\n- **PO (Product Owner)**: Validation, document sharding, alignment\n- **SM (Scrum Master)**: Story creation, sprint planning\n- **Dev**: Code implementation, feature development\n- **QA**: Code review, testing, quality gates\n\n## 📝 How Documents Are Generated\n\n**Important**: You don't manually fill out templates! BMAD agents generate all documentation using:\n\n- **YAML Templates** (in `aidesigner-core/templates/`): Define document structure\n- **Agent Intelligence**: Agents use these templates to create tailored docs\n- **MCP Tools**: Model Context Protocol enables agents to create/modify files\n\n### Example Agent Commands\n\n```bash\n# In IDE with AiDesigner agent active:\n\"Use PM agent to create a PRD for user authentication feature\"\n\"Use Architect agent to design the database schema\"\n\"Use SM agent to create stories for Epic 1\"\n```\n\n## 🛠️ Available Commands\n\n```bash\n# Core Commands\nnpm run aidesigner # Start AiDesigner orchestrator\nnpm run codex # Launch Codex CLI\nnpm run aidesigner:codex # Same as above\nnpm run aidesigner:claude # Launch Claude chat\nnpm run aidesigner:opencode # Open code interface\nnpm run aidesigner:build # Build AiDesigner bundles\n\n# Build & Development\nnpm run build # Build all agents and bundles\nnpm run build:agents # Build agent bundles only\nnpm run build:mcp # Build MCP server\n\n# Quality\nnpm run lint # Run linter\nnpm run format # Format code\nnpm run test # Run tests\n```\n\n## 🔧 Configuration\n\n### MCP Server Configuration\n\nYour MCP servers are configured in `.mcp.json`. To modify:\n\n```bash\nnpx aidesigner init # Re-run to update MCP configuration\n```\n\n### LLM Provider Configuration\n\nSet your preferred LLM provider via environment variables:\n\n```bash\n# Claude (Anthropic)\nexport ANTHROPIC_API_KEY=\"your-key\"\n\n# GLM (ZhipuAI)\nexport GLM_API_KEY=\"your-key\"\nexport GLM_BASE_URL=\"https://open.bigmodel.cn/api/paas/v4\"\n\n# OpenAI\nexport OPENAI_API_KEY=\"your-key\"\n\n# Gemini\nexport GEMINI_API_KEY=\"your-key\"\n```\n\n## 📚 Documentation & Resources\n\n- **BMAD Methodology**: [Core Architecture](https://github.com/bacoco/aidesigner)\n- **User Guide**: Complete workflow walkthrough\n- **Expansion Packs**: Domain-specific extensions (game dev, creative writing, etc.)\n- **Community**: [Discord](https://discord.gg/aidesigner) for support and discussions\n\n## 🎓 Learning Path\n\n### New to BMAD?\n\n1. Read the [BMAD User Guide](https://github.com/bacoco/aidesigner/blob/main/docs/user-guide.md)\n2. Try the [Quick Start Tutorial](https://github.com/bacoco/aidesigner/blob/main/docs/quickstart.md)\n3. Explore [Example Projects](https://github.com/bacoco/aidesigner/tree/main/examples)\n\n### Next Steps\n\n1. ✅ Run `npm install` to install dependencies\n2. 🎯 Use **PM Agent** to create your first PRD\n3. 🏗️ Use **Architect Agent** to design your system\n4. 💻 Use **Dev Agent** to start building!\n\n---\n\n**Powered by AiDesigner** | BMAD-METHOD™ Framework\n"}}}} |