Safety Rules

参见 [shared/core/safety-rules.md](../shared/core/safety-rules.md) — 所有安全规则从共享层加载，避免跨技能重复维护。

Quick Commands

Software Development Planner

Complete workflow for planning and implementing Python software with CLI, GUI, and Web interfaces, following established project patterns from GangDan, Chou, Huan, LaPian, and NuoYi.

Pre-Development Planning

Step 1: Domain Research

Before writing any code, conduct thorough research:

1. Academic Literature Search

- Search Google Scholar, CNKI, IEEE, ACM for relevant papers - Download key PDFs to pdf/ directory in project root - Extract core concepts and methodologies - Identify evaluation criteria and metrics

1. Existing Solutions Analysis

- Search GitHub for similar projects - Identify feature gaps and improvement opportunities - Note UI/UX patterns and architectural decisions

1. Requirements Synthesis

- Combine academic findings with practical needs - Define functional requirements with citations - Establish non-functional requirements (performance, usability)

Step 2: Architecture Design

Design the system before implementation:

Software Name (v1.0)
├── Core Features (from research)
│   ├── Feature 1: [description with citation]
│   ├── Feature 2: [description with citation]
│   └── Feature 3: [description with citation]
├── Data Models
│   ├── Model 1: fields, relationships
│   └── Model 2: fields, relationships
├── Algorithms
│   ├── Algorithm 1: input, output, complexity
│   └── Algorithm 2: input, output, complexity
└── User Interfaces
    ├── CLI: commands, flags, arguments
    ├── GUI: windows, panels, controls
    └── Web: routes, templates, API endpoints

Step 3: Module Specification

Define each module with clear responsibilities and size targets. The cli.py module handles command-line argument parsing and routing, targeting around 100 lines. The gui.py module provides PySide6 window, controls, and event handlers, targeting around 200 lines. The app.py module contains Flask routes and API endpoints, targeting around 100 lines. The core.py module implements business logic, algorithms, and data models, targeting around 200 lines. The api.py module provides the unified Python API with ToolResult, targeting around 100 lines. Total target is 500+ lines across all modules.

Interface Requirements

CLI (Command-Line Interface)

Follow unified flag conventions from GangDan:

import argparse

def main():
    parser = argparse.ArgumentParser(
        prog="softwarename",
        description="Software description",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    
    # Unified flags (required)
    parser.add_argument("-V", "--version", action="version", version=f"softwarename {__version__}")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    parser.add_argument("-o", "--output", help="Output path")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")
    parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
    
    # Mode selection
    subparsers = parser.add_subparsers(dest="mode")
    
    # GUI mode
    gui_parser = subparsers.add_parser("gui", help="Launch GUI")
    gui_parser.add_argument("--no-web", action="store_true", help="Disable embedded web server")
    
    # Web mode
    web_parser = subparsers.add_parser("web", help="Launch web server")
    web_parser.add_argument("--host", default="127.0.0.1")
    web_parser.add_argument("--port", type=int, default=5000)
    
    # CLI operations
    cli_parser = subparsers.add_parser("cli", help="CLI mode")
    cli_parser.add_argument("input", help="Input file or data")

Entry Points (following GangDan pattern): The software supports multiple entry points. The default invocation launches GUI or web based on context. Explicit GUI mode uses softwarename gui. Web server mode uses softwarename web. CLI mode uses softwarename cli <args>. Module invocation uses python -m packagename.

GUI (PySide6 Interface)

Use default PySide6 styling - NO custom colors, fonts, or backgrounds:

from PySide6.QtWidgets import (
    QApplication, QMainWindow, QWidget, QVBoxLayout, 
    QHBoxLayout, QPushButton, QLabel, QLineEdit, 
    QComboBox, QSpinBox, QDoubleSpinBox, QTableWidget,
    QTabWidget, QGroupBox, QFileDialog, QMessageBox,
)
from PySide6.QtCore import Qt
import pyqtgraph as pg

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Software Name v1.0")
        self.setMinimumSize(800, 600)
        
        # Central widget with default styling
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # Controls in group box
        control_group = QGroupBox("Parameters")
        control_layout = QHBoxLayout(control_group)
        
        # Input controls
        self.input_edit = QLineEdit()
        self.input_edit.setPlaceholderText("Enter input...")
        control_layout.addWidget(QLabel("Input:"))
        control_layout.addWidget(self.input_edit)
        
        # Action buttons
        btn_run = QPushButton("Run")
        btn_run.clicked.connect(self.run_analysis)
        control_layout.addWidget(btn_run)
        
        layout.addWidget(control_group)
        
        # Visualization with pyqtgraph
        self.plot_widget = pg.PlotWidget()
        self.plot_widget.setBackground('w')  # White background for plots
        self.plot_widget.showGrid(x=True, y=True)
        layout.addWidget(self.plot_widget)
        
        # Results table
        self.results_table = QTableWidget()
        self.results_table.setColumnCount(4)
        self.results_table.setHorizontalHeaderLabels(["ID", "Name", "Value", "Score"])
        layout.addWidget(self.results_table)

GUI Design Principles: Three principles guide GUI implementation. First, use default styling only with system default colors, system default fonts, no custom backgrounds, and no custom stylesheets. Second, follow a consistent layout structure with the control panel with parameters at the top, visualization area with pyqtgraph in the middle, and results table or log output at the bottom. Third, select appropriate control types: QLineEdit for text input, QSpinBox or QDoubleSpinBox for numeric input, QComboBox for selections, QCheckBox for boolean options, and QPushButton for actions.

Web (Flask Interface)

from flask import Flask, render_template, jsonify, request

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/analyze", methods=["POST"])
def analyze():
    data = request.json
    result = perform_analysis(data)
    return jsonify(result.to_dict())

@app.route("/api/results/<id>")
def get_results(id):
    result = get_stored_result(id)
    return jsonify(result.to_dict())

def run_server(host="127.0.0.1", port=5000):
    print(f"Starting server at http://{host}:{port}")
    app.run(host=host, port=port, debug=False)

ToolResult Pattern

All API functions must return ToolResult:

from dataclasses import dataclass, field
from typing import Any, Optional

@dataclass
class ToolResult:
    success: bool
    data: Any = None
    error: Optional[str] = None
    metadata: dict = field(default_factory=dict)

    def to_dict(self) -> dict:
        return {
            "success": self.success,
            "data": self.data,
            "error": self.error,
            "metadata": self.metadata,
        }

Sample Data Requirements

Create sample data for testing and demonstration:

Data File Structure

data/
├── sample_input.json      # Example input data
├── sample_results.json    # Expected output for testing
├── test_cases.json        # Test case definitions
└── reference_data.csv     # Reference/benchmark data

Sample Data Template

{
  "description": "Sample input for testing",
  "version": "1.0",
  "cases": [
    {
      "id": "case_001",
      "name": "Basic test case",
      "input": {
        "param1": "value1",
        "param2": 100
      },
      "expected_output": {
        "result": "expected_result",
        "score": 0.95
      }
    }
  ]
}

Documentation Structure

README.md (English)

Required sections, each 200+ words: Section 1 covers project background including context, problem statement, and motivation. Section 2 describes application scenarios with use cases, target users, and workflows. Section 3 details hardware compatibility including CPU, GPU, and memory requirements. Section 4 specifies operating system support for Windows, macOS, and Linux. Section 5 lists dependencies including Python version and required packages. Section 6 provides installation instructions for pip install, from source, and configuration. Section 7 explains usage covering CLI commands, GUI operation, and Web interface. Section 8 includes screenshots with placeholders and descriptions. Section 9 covers license information with the GPLv3 statement.

README_CN.md (Chinese)

Same structure as English, translated: Section 1 covers 项目背景 (project background). Section 2 covers 应用场景 (application scenarios). Section 3 covers 兼容硬件 (hardware compatibility). Section 4 covers 操作系统 (operating systems). Section 5 covers 依赖环境 (dependencies). Section 6 covers 安装过程 (installation). Section 7 covers 使用方法 (usage). Section 8 covers 运行截图 (screenshots). Section 9 covers 授权协议 (license).

README Template

The README template provides a structured format for documentation. Each section should contain at least 200 words to ensure adequate detail. The Project Background section describes the context, problem, and motivation for the software, including academic context and practical need. The Application Scenarios section describes specific use cases, target users, and typical workflows. The Hardware Compatibility section describes CPU requirements, GPU needs if any, memory requirements, and storage needs. The Operating Systems section describes support for Windows, macOS, and Linux with specific version requirements. The Dependencies section lists Python version requirement, core dependencies with version constraints, and optional dependencies. The Installation section provides step-by-step installation instructions for pip, conda, and from-source methods. The Usage section provides CLI examples, GUI instructions, and Web interface usage. The Screenshots section displays GUI and Web interface images. The License section states GPLv3 and references the LICENSE file.

Project File Structure

project_name/
├── pyproject.toml          # Package configuration
├── requirements.txt        # Dependencies list
├── LICENSE                 # GPLv3 license
├── README.md               # English documentation
├── README_CN.md            # Chinese documentation
├── MANIFEST.in             # Package manifest
├── upload_pypi.sh          # PyPI upload script (Unix)
├── upload_pypi.bat         # PyPI upload script (Windows)
├── pdf/                    # Academic reference papers
│   ├── paper1.pdf
│   └── paper2.pdf
├── data/                   # Sample data
│   ├── sample_input.json
│   └── test_cases.json
├── images/                 # Screenshots
│   └── placeholder.png
├── tests/                  # Test suite
│   ├── __init__.py
│   ├── conftest.py
│   └── test_core.py
└── packagename/            # Main package
    ├── __init__.py         # Version and exports
    ├── __main__.py         # python -m entry
    ├── cli.py              # CLI implementation
    ├── gui.py              # GUI implementation
    ├── app.py              # Flask web app
    ├── core.py             # Business logic
    └── api.py              # Unified API

Usage Examples

Planning a Data Analysis Tool

/planner research "time series analysis with interactive visualization"
/planner design "TimeViz - time series analysis tool"
/planner modules --interface cli,web
/planner docs --lang zh,en
/planner verify

Planning a Scientific Simulation

/planner research "molecular dynamics simulation with GPU acceleration"
/planner design "MolSim" --domain scientific
/planner modules --interface gui,cli

Quick Start for Small Projects

/planner design "MyTool" --minimal
/planner modules --single-file

Troubleshooting

Research phase returns too broad results

• Fix: Narrow with --domain scientific|web|cli|gui flag; add --year 2024-2026 for recent papers; exclude tangential fields with --exclude-field

Module specification too abstract

• Fix: Use /planner modules --detailed for API-level decomposition; add --example to generate pseudocode for each module

Documentation generation creates empty stubs

• Fix: Ensure module specs are complete before running docs; use /planner docs --fill to auto-populate from module signatures

Interface design conflicts

• Fix: Use /planner design --resolve to detect and resolve conflicts between CLI/GUI/Web interfaces

Edge Cases

• Monorepo planning: Use --monorepo flag to generate per-package module specs with shared dependency tracking
• Legacy migration: --migrate-from <old-spec> compares old architecture against new plan, flags breaking changes
• Multi-language projects: Specify --languages python,rust,typescript for cross-language interface compatibility verification
• Real-time systems: Use --domain realtime to add latency budget and concurrency model to module specs
• Embedded/constrained: --domain embedded adds memory budget and dependency size limits
• Empty project seed: If no prior code exists, /planner design <name> --seed generates minimal template alongside architecture

AIGC-Aware Output

Software planning documents must be project-specific with concrete numbers and constraints, not universal template text. See rules/anti-aigc.md for complete anti-AIGC detection rules.

Key requirements:

• Requirements must include quantified constraints, not "good user experience"
• Module descriptions must include line count targets and dependency direction
• Technology choices must include rejection reasons for alternatives
• Every "excellent/robust/powerful" must be replaced with measurable criteria

Version History

Rules

• [rules/pre-development.md](rules/pre-development.md) - Research and planning phase
• [rules/interface-design.md](rules/interface-design.md) - CLI/GUI/Web patterns
• [rules/documentation.md](rules/documentation.md) - README requirements
• [rules/sample-data.md](rules/sample-data.md) - Test data creation
• [rules/anti-aigc.md](rules/anti-aigc.md) - 软件规划反AIGC检测规则

Verification Checklist

Before considering the project complete, verify the following items. Code should be 500+ lines total across all modules. CLI should have unified flags (-V, -v, -o, --json, -q). GUI should use default PySide6 styling without custom styling. Web interface should have a REST API. All functions should return ToolResult. Sample data files should exist in the data directory. Test cases should be defined. README.md should have all 9 sections with 200+ words each. README_CN.md should have all 9 sections with 200+ words each. Academic PDFs should be present in the pdf/ directory. GPLv3 LICENSE file should exist. requirements.txt should exist. pyproject.toml should be configured correctly. PyPI upload scripts should exist.

Quick Start Template

# Create project structure
mkdir -p project_name/{pdf,data,images,tests,packagename}

# Create required files
touch project_name/{pyproject.toml,requirements.txt,LICENSE,README.md,README_CN.md}
touch project_name/upload_pypi.{sh,bat}

# Create package files
touch project_name/packagename/{__init__.py,__main__.py,cli.py,gui.py,app.py,core.py,api.py}

# Create test files
touch project_name/tests/{__init__.py,conftest.py,test_core.py}

See Also

• /python-project from python-project-developer — Implement planned project structure
• /architect design from master-architect — Detailed architecture decomposition
• /agent-patterns from coding-agent-patterns — Integration patterns for multi-interface applications