cc-devflow 1.0.1

package/docs/guides/getting-started.md

@@ -0,0 +1,204 @@
+# Getting Started with cc-devflow
+
+[中文文档](./getting-started.zh-CN.md) | [English](./getting-started.md)
+
+---
+
+## 📋 Overview
+
+This guide will help you get started with cc-devflow, from installation to your first requirement development.
+
+## 🚀 Prerequisites
+
+- [Claude Code](https://claude.ai/code) installed and configured
+- Git repository initialized
+- Node.js project (optional, for additional quality checks)
+
+## 📦 Installation
+
+### Quick Install
+
+```bash
+# Clone .claude configuration to your project
+pnpm dlx tiged Dimon94/cc-devflow/.claude .claude
+```
+
+### Manual Install
+
+```bash
+# Download and extract
+curl -L https://github.com/Dimon94/cc-devflow/archive/main.zip -o cc-devflow.zip
+unzip cc-devflow.zip
+cp -r cc-devflow-main/.claude .claude
+rm -rf cc-devflow.zip cc-devflow-main
+```
+
+## ✅ Verify Installation
+
+Run the verification script:
+
+```bash
+.claude/scripts/verify-setup.sh
+```
+
+This script will check:
+- All required files and directories exist
+- Scripts have execute permissions
+- Git repository is properly configured
+
+## 🎯 Your First Requirement
+
+### Step 1: Start Development Flow
+
+```bash
+/flow-new "REQ-001|User Authentication|https://docs.example.com/auth"
+```
+
+This will:
+1. Initialize requirement structure
+2. Generate PRD
+3. Generate UI prototype (if needed)
+4. Create technical design
+5. Generate EPIC and TASKS
+6. Execute development
+7. Run QA tests
+8. Prepare release
+
+### Step 2: Check Progress
+
+```bash
+/flow-status REQ-001
+```
+
+### Step 3: Resume If Interrupted
+
+```bash
+/flow-restart "REQ-001"
+```
+
+## 🛠️ Core Scripts
+
+### Environment Check
+```bash
+bash .claude/scripts/check-prerequisites.sh
+```
+
+### View Task Status
+```bash
+bash .claude/scripts/check-task-status.sh --verbose
+```
+
+### Mark Task Complete
+```bash
+bash .claude/scripts/mark-task-complete.sh T001
+```
+
+### Generate Status Report
+```bash
+bash .claude/scripts/generate-status-report.sh --format markdown
+```
+
+## 🧪 Running Tests
+
+### Script Tests
+```bash
+# Run all tests
+bash .claude/tests/run-all-tests.sh --scripts
+
+# Run specific test
+bash .claude/tests/scripts/test_check_prerequisites.sh
+```
+
+### Constitution Tests
+```bash
+bash .claude/tests/constitution/run_all_constitution_tests.sh
+```
+
+## 📊 Interactive Demo
+
+Run the interactive demo to see the complete workflow:
+
+```bash
+python3 .claude/scripts/demo.py
+```
+
+## 🔧 Configuration
+
+### Minimum Configuration
+
+Edit `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allowGitOperations": true,
+    "allowNetworkRequests": true,
+    "allowSubprocesses": true
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+# Quality gates
+export MIN_TEST_COVERAGE=80
+export STRICT_TYPE_CHECKING=true
+
+# Flow behavior
+export FLOW_AUTO_APPROVE=false
+```
+
+## 📚 Next Steps
+
+- [Command Reference](../commands/README.md) - Learn all available commands
+- [Workflow Guide](./workflow-guide.md) - Understand the development workflow
+- [Best Practices](./best-practices.md) - Follow recommended practices
+
+## 🚨 Troubleshooting
+
+### Issue: Scripts not executable
+
+```bash
+chmod +x .claude/scripts/*.sh
+chmod +x .claude/hooks/*.sh
+```
+
+### Issue: Git not initialized
+
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+```
+
+### Issue: Tests failing
+
+```bash
+# Check prerequisites
+bash .claude/scripts/check-prerequisites.sh
+
+# Run tests with verbose output
+VERBOSE=true bash .claude/tests/run-all-tests.sh --scripts
+```
+
+## 💡 Tips
+
+1. **Always check progress** with `/flow-status` before continuing work
+2. **Use `/flow-verify`** to check document consistency
+3. **Enable debug mode** if you encounter issues: `export FLOW_DEBUG=1`
+4. **Read the Constitution** to understand quality standards
+
+## 🆘 Getting Help
+
+- [GitHub Issues](https://github.com/Dimon94/cc-devflow/issues)
+- [Documentation](../../docs/)
+- [Contributing Guide](../../CONTRIBUTING.md)
+
+---
+
+**Ready to start? Run your first command:**
+
+```bash
+/flow-new "REQ-001|My First Feature"
+```

package/docs/guides/getting-started.zh-CN.md

@@ -0,0 +1,152 @@
+# 🚀 快速开始指南
+
+## 📦 安装
+
+### 方式 1: 使用 npx（推荐）
+
+```bash
+pnpm dlx tiged Dimon94/cc-devflow/.claude .claude
+```
+
+### 方式 2: 手动下载
+
+```bash
+curl -L https://github.com/Dimon94/cc-devflow/archive/main.zip -o cc-devflow.zip
+unzip cc-devflow.zip
+cp -r cc-devflow-main/.claude .claude
+rm -rf cc-devflow.zip cc-devflow-main
+```
+
+## ✅ 验证安装
+
+```bash
+.claude/scripts/verify-setup.sh
+```
+
+**预期输出**:
+```
+✅ All checks passed!
+cc-devflow is ready to use.
+```
+
+## 🎮 交互式演示
+
+运行完整演示了解工作流：
+
+```bash
+python3 .claude/scripts/demo.py
+```
+
+## 🎯 第一个需求
+
+### 1. 启动需求开发
+
+```bash
+/flow-new "REQ-001|用户认证功能|https://docs.example.com/auth"
+```
+
+### 2. 查看进度
+
+```bash
+/flow-status REQ-001
+```
+
+### 3. 如果中断，恢复开发
+
+```bash
+/flow-restart "REQ-001"
+```
+
+### 4. 验证一致性
+
+```bash
+/flow-verify "REQ-001"
+```
+
+### 5. 执行 QA
+
+```bash
+/flow-qa "REQ-001"
+```
+
+### 6. 创建发布
+
+```bash
+/flow-release "REQ-001"
+```
+
+## 📋 核心脚本
+
+```bash
+# 快速环境检查
+bash .claude/scripts/check-prerequisites.sh
+
+# 查看任务状态
+bash .claude/scripts/check-task-status.sh --verbose
+
+# 标记任务完成
+bash .claude/scripts/mark-task-complete.sh T001
+
+# 生成状态报告
+bash .claude/scripts/generate-status-report.sh --format markdown
+
+# 验证 Constitution 合规
+bash .claude/scripts/manage-constitution.sh verify
+```
+
+## 🧪 运行测试
+
+```bash
+# 运行所有脚本测试
+bash .claude/tests/run-all-tests.sh --scripts
+
+# 运行 Constitution 测试
+bash .claude/tests/constitution/run_all_constitution_tests.sh
+
+# 运行特定测试
+bash .claude/tests/scripts/test_check_prerequisites.sh
+```
+
+## ⚙️ 基础配置
+
+最小配置 (`.claude/settings.json`):
+
+```json
+{
+  "permissions": {
+    "allowGitOperations": true,
+    "allowNetworkRequests": true,
+    "allowSubprocesses": true
+  }
+}
+```
+
+## 🚨 常见问题
+
+### Q: 安装后命令无法识别？
+
+**A**: 确保在项目根目录执行命令，且 `.claude/` 目录存在。
+
+### Q: Git 仓库未初始化？
+
+**A**: 先初始化 Git 仓库：
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+```
+
+### Q: 权限不足？
+
+**A**: 给脚本添加执行权限：
+```bash
+chmod +x .claude/scripts/*.sh
+chmod +x .claude/hooks/*.sh
+```
+
+## 📚 下一步
+
+- [完整命令参考](../commands/README.md)
+- [工作流详解](./workflow-guide.md)
+- [最佳实践](./best-practices.md)
+- [故障排查](./troubleshooting.md)

package/lib/adapters/adapter-interface.js

@@ -0,0 +1,57 @@
+/**
+ * Abstract class representing an Agent Adapter.
+ * Adapters bridge the gap between cc-devflow and specific AI agent CLI tools.
+ */
+class AgentAdapter {
+    constructor() {
+        if (this.constructor === AgentAdapter) {
+            throw new Error("Cannot instantiate abstract class AgentAdapter");
+        }
+    }
+
+    /**
+     * The unique name of the adapter (e.g., 'claude', 'codex').
+     * @returns {string}
+     */
+    get name() {
+        throw new Error("Method 'name' must be implemented.");
+    }
+
+    /**
+     * The configuration folder name expected in the user's project (e.g., '.claude').
+     * @returns {string}
+     */
+    get folder() {
+        throw new Error("Method 'folder' must be implemented.");
+    }
+
+    /**
+     * Detects if this adapter is applicable for the current environment.
+     * Checks for folder existence, environment variables, or other indicators.
+     * @returns {Promise<boolean>}
+     */
+    async detect() {
+        throw new Error("Method 'detect()' must be implemented.");
+    }
+
+    /**
+     * Executes a command using this adapter's underlying agent.
+     * @param {string} command - The command to execute.
+     * @param {string[]} args - Arguments for the command.
+     * @param {Object} options - Execution options.
+     * @returns {Promise<Object>} The result of the execution.
+     */
+    async execute(command, args = [], options = {}) {
+        throw new Error("Method 'execute()' must be implemented.");
+    }
+
+    /**
+     * Returns the capabilities of this adapter.
+     * @returns {string[]} List of capabilities (e.g., 'shell', 'network').
+     */
+    get capabilities() {
+        return [];
+    }
+}
+
+module.exports = AgentAdapter;

package/lib/adapters/claude-adapter.js

@@ -0,0 +1,74 @@
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const AgentAdapter = require('./adapter-interface');
+
+class ClaudeAdapter extends AgentAdapter {
+    get name() {
+        return 'claude';
+    }
+
+    get folder() {
+        return '.claude';
+    }
+
+    /**
+     * Detects if the current environment is set up for Claude.
+     * Checks for .claude directory or ANTHROPIC_API_KEY env var.
+     */
+    async detect() {
+        // 1. Check for directory presence
+        const configPath = path.resolve(process.cwd(), this.folder);
+        if (fs.existsSync(configPath)) {
+            return true;
+        }
+
+        // 2. Check for environment variable
+        if (process.env.ANTHROPIC_API_KEY) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Executes a command using the 'claude' CLI tool.
+     * Assumes 'claude' is in the PATH or handled via `npx claude`.
+     * For MVP we assume it's installed globally or accessible.
+     */
+    async execute(command, args = [], options = {}) {
+        return new Promise((resolve, reject) => {
+            // In a real scenario, we might want to sanitize input or map commands 
+            // from our internal schema to claude-code's CLI schema.
+            // For now, we pass through.
+
+            const cliCmd = 'claude'; // Or 'npx', ['claude', ...args]
+            const cliArgs = [command, ...args];
+
+            const child = spawn(cliCmd, cliArgs, {
+                stdio: 'inherit',
+                shell: false,
+                ...options
+            });
+
+            child.on('error', (err) => {
+                reject(err);
+            });
+
+            child.on('close', (code) => {
+                if (code === 0) {
+                    resolve({ code, msg: 'Success' });
+                } else {
+                    resolve({ code, msg: `Exited with code ${code}` }); // Or reject?
+                }
+            });
+        });
+    }
+
+    get capabilities() {
+        // Claude code is powerful, has shell and network usually.
+        return ['shell', 'network', 'filesystem'];
+    }
+}
+
+module.exports = ClaudeAdapter;

package/lib/adapters/codex-adapter.js

@@ -0,0 +1,40 @@
+const fs = require('fs');
+const path = require('path');
+const AgentAdapter = require('./adapter-interface');
+
+class CodexAdapter extends AgentAdapter {
+    get priority() {
+        for (const key of Object.keys(process.env)) {
+            if (key.startsWith('CODEX_')) return 100;
+        }
+        return 0;
+    }
+
+    get name() {
+        return 'codex';
+    }
+
+    get folder() {
+        return '.codex';
+    }
+
+    async detect() {
+        for (const key of Object.keys(process.env)) {
+            if (key.startsWith('CODEX_')) return true;
+        }
+
+        const configPath = path.resolve(process.cwd(), this.folder);
+        return fs.existsSync(configPath);
+    }
+
+    async execute(command, args = [], options = {}) {
+        console.log(`[CodexAdapter] Executing: ${command} ${args.join(' ')}`);
+        return { code: 0, msg: 'Codex executed (simulated)' };
+    }
+
+    get capabilities() {
+        return ['code-generation'];
+    }
+}
+
+module.exports = CodexAdapter;

package/lib/adapters/config-validator.js

@@ -0,0 +1,68 @@
+/**
+ * Runtime configuration validator using Zod.
+ * Ensures adapters.yml conforms to expected schema with secure defaults.
+ */
+const { z } = require('zod');
+
+// ============================================================================
+// Schema Definition
+// ============================================================================
+
+const PoliciesSchema = z.object({
+    allow_shell: z.boolean().default(false),
+    allow_network: z.boolean().default(false),
+    audit_log_path: z.string().optional()
+}).strict();
+
+const AdaptersConfigSchema = z.object({
+    preferred: z.string().nullable().optional().default(null),
+    policies: PoliciesSchema.default({})
+}).strict();
+
+const RootConfigSchema = z.object({
+    adapters: AdaptersConfigSchema.default({})
+});
+
+// ============================================================================
+// Validation Functions
+// ============================================================================
+
+/**
+ * Parse and validate the raw YAML config object.
+ * Returns validated config with defaults applied.
+ * 
+ * @param {unknown} rawConfig - Raw parsed YAML object
+ * @returns {{ success: true, data: object } | { success: false, error: string }}
+ */
+function validateConfig(rawConfig) {
+    const result = RootConfigSchema.safeParse(rawConfig ?? {});
+
+    if (!result.success) {
+        const issues = result.error.issues
+            .map(i => `  - ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        return {
+            success: false,
+            error: `Configuration validation failed:\n${issues}`
+        };
+    }
+
+    return { success: true, data: result.data };
+}
+
+/**
+ * Get default config when file is missing or empty.
+ * 
+ * @returns {object} Default configuration
+ */
+function getDefaultConfig() {
+    return RootConfigSchema.parse({});
+}
+
+module.exports = {
+    validateConfig,
+    getDefaultConfig,
+    // Export schemas for testing
+    AdaptersConfigSchema,
+    RootConfigSchema
+};

package/lib/adapters/logger.js

@@ -0,0 +1,42 @@
+/**
+ * Structural Logger for Adapter System.
+ * Outputs JSON format for machine readability and better observability.
+ */
+class Logger {
+    constructor() {
+        this.enabled = true;
+    }
+
+    log(level, message, context = {}) {
+        if (!this.enabled) return;
+
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            ...context
+        };
+
+        console.log(JSON.stringify(entry));
+    }
+
+    info(message, context) {
+        this.log('INFO', message, context);
+    }
+
+    warn(message, context) {
+        this.log('WARN', message, context);
+    }
+
+    error(message, context) {
+        this.log('ERROR', message, context);
+    }
+
+    debug(message, context) {
+        if (process.env.DEBUG) {
+            this.log('DEBUG', message, context);
+        }
+    }
+}
+
+module.exports = new Logger();