@jahanxu/trellis 0.4.2 → 0.5.1

package/dist/templates/trellis/paths.README.md

@@ -1,277 +0,0 @@
-# 三角色协作路径配置说明
-
-> 框架层与业务层分离，支持不同项目自定义目录结构
-
----
-
-## 设计理念
-
-**问题**：`deliverables/` 及其子目录是业务层概念，不应该在框架层硬编码。
-
-**解决**：通过 `.trellis/paths.yaml` 配置文件，将路径定义从框架层抽离到项目配置层。
-
-**优点**：
-- ✅ 框架通用性更强，可适配不同项目
-- ✅ 一处配置，处处生效
-- ✅ 向后兼容（配置文件不存在时使用默认值）
-
----
-
-## 配置文件
-
-### 位置
-
-`.trellis/paths.yaml`
-
-### 默认配置
-
-如果此文件不存在，使用以下默认值：
-
-```yaml
-deliverables_base: "deliverables"
-
-role_outputs:
-  pm:
-    dir: "requirements"
-  designer:
-    dir: "prototypes"
-  frontend:
-    dir: "production/features"
-
-pools:
-  pm: "requirements"
-  designer: "prototypes"
-  frontend: "implementations"
-```
-
-### 自定义示例
-
-#### 示例1：修改基础目录名
-
-```yaml
-# 将 deliverables/ 改为 outputs/
-deliverables_base: "outputs"
-
-role_outputs:
-  pm:
-    dir: "requirements"
-  designer:
-    dir: "prototypes"
-  frontend:
-    dir: "production/features"
-```
-
-**结果**：
-- PM 产出 → `outputs/requirements/`
-- Designer 产出 → `outputs/prototypes/`
-- Frontend 产出 → `outputs/production/features/`
-
-#### 示例2：完全自定义
-
-```yaml
-deliverables_base: "artifacts"
-
-role_outputs:
-  pm:
-    dir: "specs"
-  designer:
-    dir: "designs"
-  frontend:
-    dir: "code"
-```
-
-**结果**：
-- PM 产出 → `artifacts/specs/`
-- Designer 产出 → `artifacts/designs/`
-- Frontend 产出 → `artifacts/code/`
-
-#### 示例3：多级目录
-
-```yaml
-deliverables_base: "dist"
-
-role_outputs:
-  pm:
-    dir: "docs/requirements"
-  designer:
-    dir: "docs/designs"
-  frontend:
-    dir: "src/features"
-```
-
-**结果**：
-- PM 产出 → `dist/docs/requirements/`
-- Designer 产出 → `dist/docs/designs/`
-- Frontend 产出 → `dist/src/features/`
-
----
-
-## 使用方式
-
-### 在 Python 脚本中使用
-
-```python
-from common.project_paths import get_output_dir_for_task, get_repo_root
-
-repo_root = get_repo_root()
-role = "pm"
-task_id = "user-login"
-
-# 获取产出目录
-output_dir = get_output_dir_for_task(repo_root, role, task_id)
-# 结果：deliverables/requirements/user-login（默认配置）
-# 或：outputs/specs/user-login（自定义配置）
-```
-
-### 在命令行中使用
-
-```bash
-# 查看当前配置
-python3 .trellis/scripts/common/project_paths.py
-
-# 输出：
-# === Loaded Configuration ===
-# Deliverables base: deliverables
-#
-# Role output directories:
-#   pm: deliverables/requirements
-#   designer: deliverables/prototypes
-#   frontend: deliverables/production/features
-```
-
-### 在 AI 命令中使用
-
-AI 读取配置并自动使用正确的路径：
-
-```bash
-# AI 执行 /trellis:handoff 时会：
-1. 读取 .trellis/paths.yaml（如果存在）
-2. 获取当前角色的产出目录配置
-3. 创建产出目录并复制文件
-```
-
----
-
-## API 参考
-
-### `load_paths_config(repo_root: Path) -> Dict`
-
-加载路径配置，如果配置文件不存在则返回默认配置。
-
-### `get_deliverables_base(repo_root: Path) -> str`
-
-获取产出物基础目录名（如 `deliverables`）。
-
-### `get_role_output_dir(repo_root: Path, role: str) -> str`
-
-获取指定角色的产出目录路径。
-
-**参数**：
-- `role`: `pm`、`designer` 或 `frontend`
-
-**返回**：
-- 完整路径，如 `deliverables/requirements`
-
-### `get_output_dir_for_task(repo_root: Path, role: str, task_id: str) -> str`
-
-获取指定任务的完整产出目录路径。
-
-**返回**：
-- 完整路径，如 `deliverables/requirements/user-login`
-
-### `get_pool_name(role: str) -> str`
-
-获取指定角色的任务池名称。
-
-**返回**：
-- 池名称，如 `requirements`、`prototypes`、`implementations`
-
----
-
-## 依赖
-
-### 可选依赖：PyYAML
-
-```bash
-pip install pyyaml
-```
-
-如果未安装 PyYAML：
-- ⚠️ 会打印警告信息
-- ✅ 仍然可以正常工作（使用默认配置）
-
----
-
-## 迁移指南
-
-### 从硬编码路径迁移
-
-**之前**：路径硬编码在文档中
-
-```markdown
-| `pm` | `deliverables/requirements/{task-id}/` |
-```
-
-**现在**：使用配置化路径
-
-```python
-from project_paths import get_output_dir_for_task
-output_dir = get_output_dir_for_task(repo_root, "pm", task_id)
-```
-
-### 为现有项目添加自定义配置
-
-1. 创建 `.trellis/paths.yaml`
-2. 定义你的目录结构
-3. 无需修改任何代码，AI 会自动读取新配置
-
----
-
-## 注意事项
-
-1. **池子状态文件名不建议修改**
-   - `.trellis/pool/requirements.json`
-   - `.trellis/pool/prototypes.json`
-   - `.trellis/pool/implementations.json`
-   - 这些是框架层的内部文件
-
-2. **产出目录可以任意定制**
-   - `deliverables/` 及其子目录
-   - 这些是业务层的目录
-
-3. **配置文件是可选的**
-   - 不存在时使用默认值
-   - 向后兼容
-
----
-
-## 常见问题
-
-### Q: 修改配置后需要重启吗？
-A: 不需要。每次执行命令时都会重新读取配置。
-
-### Q: 可以为不同角色使用完全不同的基础目录吗？
-A: 可以，通过多级路径实现：
-```yaml
-role_outputs:
-  pm:
-    dir: "../docs/specs"  # 相对路径
-  designer:
-    dir: "ui/designs"
-  frontend:
-    dir: "src/features"
-```
-
-### Q: 其他项目如何快速采用？
-A:
-1. 复制 `.trellis/` 整个目录到新项目
-2. 修改 `.trellis/paths.yaml` 适配新项目的目录结构
-3. 立即可用，无需修改任何代码
-
----
-
-## 相关文档
-
-- [三角色协作工作流](../workflow.md)
-- [Handoff 命令说明](../../.claude/commands/trellis/handoff.md)
-- [项目路径工具源码](../scripts/common/project_paths.py)

package/dist/templates/trellis/paths.yaml

@@ -1,41 +0,0 @@
-# Trellis 三角色协作路径配置
-#
-# 此文件定义项目特定的目录结构，不同项目可以自定义。
-# 如果此文件不存在，将使用默认值。
-
-# 产出物基础目录
-deliverables_base: "deliverables"
-
-# 角色产出目录映射
-role_outputs:
-  pm:
-    # PM 角色的产出目录（相对于 deliverables_base）
-    dir: "requirements"
-    # 完整路径（自动计算：deliverables_base + dir）
-    # full_path: "deliverables/requirements"
-
-  designer:
-    # Designer 角色的产出目录
-    dir: "prototypes"
-    # full_path: "deliverables/prototypes"
-
-  frontend:
-    # Frontend 角色的产出目录
-    dir: "production/features"
-    # full_path: "deliverables/production/features"
-
-# 任务池配置（池子状态文件名，通常不需要修改）
-pools:
-  pm: "requirements"
-  designer: "prototypes"
-  frontend: "implementations"
-
-# 示例：其他项目可能的配置
-# deliverables_base: "outputs"
-# role_outputs:
-#   pm:
-#     dir: "specs"
-#   designer:
-#     dir: "designs"
-#   frontend:
-#     dir: "code"

package/dist/templates/trellis/pool/implementations.json

@@ -1,5 +0,0 @@
-{
-  "available": [],
-  "consumed": [],
-  "last_updated": null
-}

package/dist/templates/trellis/pool/prototypes.json

@@ -1,5 +0,0 @@
-{
-  "available": [],
-  "consumed": [],
-  "last_updated": null
-}

package/dist/templates/trellis/pool/requirements.json

@@ -1,5 +0,0 @@
-{
-  "available": [],
-  "consumed": [],
-  "last_updated": null
-}

package/dist/templates/trellis/scripts/common/project_paths.py

@@ -1,189 +0,0 @@
-#!/usr/bin/env python3
-"""
-Project-specific path configuration loader.
-
-Reads .trellis/paths.yaml to get project-specific directory structure.
-Falls back to defaults if config file doesn't exist.
-
-This separates framework layer from business layer, allowing different
-projects to use different directory structures.
-"""
-
-import sys
-from pathlib import Path
-from typing import Optional, Dict
-
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
-
-# =============================================================================
-# Default Configuration (Framework Layer)
-# =============================================================================
-
-DEFAULT_CONFIG = {
-    "deliverables_base": "deliverables",
-    "role_outputs": {
-        "pm": {"dir": "requirements"},
-        "designer": {"dir": "prototypes"},
-        "frontend": {"dir": "production/features"},
-    },
-    "pools": {
-        "pm": "requirements",
-        "designer": "prototypes",
-        "frontend": "implementations",
-    },
-}
-
-# =============================================================================
-# Configuration Loader
-# =============================================================================
-
-
-def load_paths_config(repo_root: Path) -> Dict:
-    """Load paths configuration from .trellis/paths.yaml.
-
-    Args:
-        repo_root: Repository root path
-
-    Returns:
-        Configuration dict with paths
-    """
-    config_file = repo_root / ".trellis" / "paths.yaml"
-
-    # If config file doesn't exist, use defaults
-    if not config_file.exists():
-        return DEFAULT_CONFIG.copy()
-
-    # If yaml not available, use defaults
-    if not HAS_YAML:
-        print(
-            "Warning: PyYAML not installed, using default paths. "
-            "Install with: pip install pyyaml",
-            file=sys.stderr,
-        )
-        return DEFAULT_CONFIG.copy()
-
-    # Load config from yaml
-    try:
-        with open(config_file, "r", encoding="utf-8") as f:
-            config = yaml.safe_load(f) or {}
-
-        # Merge with defaults (in case some keys are missing)
-        merged = DEFAULT_CONFIG.copy()
-        merged.update(config)
-
-        # Ensure role_outputs has all roles
-        for role in ["pm", "designer", "frontend"]:
-            if role not in merged["role_outputs"]:
-                merged["role_outputs"][role] = DEFAULT_CONFIG["role_outputs"][role]
-
-        return merged
-    except Exception as e:
-        print(
-            f"Warning: Failed to load {config_file}: {e}. Using defaults.",
-            file=sys.stderr,
-        )
-        return DEFAULT_CONFIG.copy()
-
-
-def get_deliverables_base(repo_root: Path) -> str:
-    """Get deliverables base directory.
-
-    Args:
-        repo_root: Repository root path
-
-    Returns:
-        Deliverables base directory name
-    """
-    config = load_paths_config(repo_root)
-    return config.get("deliverables_base", "deliverables")
-
-
-def get_role_output_dir(repo_root: Path, role: str) -> str:
-    """Get output directory for a specific role.
-
-    Args:
-        repo_root: Repository root path
-        role: Role name (pm, designer, frontend)
-
-    Returns:
-        Full output directory path (relative to repo_root)
-    """
-    config = load_paths_config(repo_root)
-    base = config.get("deliverables_base", "deliverables")
-    role_config = config.get("role_outputs", {}).get(role, {})
-    role_dir = role_config.get("dir", "")
-
-    if not role_dir:
-        # Fallback to default
-        role_dir = DEFAULT_CONFIG["role_outputs"].get(role, {}).get("dir", "")
-
-    return f"{base}/{role_dir}"
-
-
-def get_pool_name(role: str) -> str:
-    """Get pool name for a specific role.
-
-    Args:
-        role: Role name (pm, designer, frontend)
-
-    Returns:
-        Pool name (e.g., 'requirements', 'prototypes', 'implementations')
-    """
-    # Pool names are usually fixed in framework layer
-    # But can be overridden in config if needed
-    return DEFAULT_CONFIG["pools"].get(role, role)
-
-
-def get_output_dir_for_task(repo_root: Path, role: str, task_id: str) -> str:
-    """Get complete output directory for a specific task.
-
-    Args:
-        repo_root: Repository root path
-        role: Role name (pm, designer, frontend)
-        task_id: Task ID
-
-    Returns:
-        Full output directory path (e.g., "deliverables/requirements/user-login")
-    """
-    role_dir = get_role_output_dir(repo_root, role)
-    return f"{role_dir}/{task_id}"
-
-
-# =============================================================================
-# CLI for testing
-# =============================================================================
-
-
-def main():
-    """Test configuration loading."""
-    # Add parent directory to path for imports
-    sys.path.insert(0, str(Path(__file__).parent))
-    from paths import get_repo_root
-
-    repo_root = get_repo_root()
-    config = load_paths_config(repo_root)
-
-    print("=== Loaded Configuration ===")
-    print(f"Deliverables base: {config['deliverables_base']}")
-    print("\nRole output directories:")
-    for role in ["pm", "designer", "frontend"]:
-        full_path = get_role_output_dir(repo_root, role)
-        print(f"  {role}: {full_path}")
-
-    print("\nPool names:")
-    for role in ["pm", "designer", "frontend"]:
-        pool = get_pool_name(role)
-        print(f"  {role}: {pool}")
-
-    print("\nExample output paths:")
-    for role in ["pm", "designer", "frontend"]:
-        path = get_output_dir_for_task(repo_root, role, "user-login")
-        print(f"  {role}/user-login: {path}")
-
-
-if __name__ == "__main__":
-    main()