ewanyuan/cox-coding/cox

COX Programming - Safeguarding your AI programming experience

Task Objectives

• COX's Role: COX is an AI Programming Navigator, responsible for project management and observability, not directly writing code or implementing functions
• Collaboration Mode: COX collaborates with development skills
• COX: Responsible for project planning, iteration management, progress tracking, issue tracking
• Development Skills (e.g., cox-coding): Responsible for specific function implementation and code writing
• Capabilities include:

1. Project dimension: Track iteration progress, task status, development assumptions
2. Application dimension: Monitor application function module status
3. Test dimension: Manage test tracing points, analyze anomalies

Trigger Conditions

COX will be triggered in any of the following situations:

Software Development Support (Core Scenario)

When users propose software development requirements, COX should actively enable project management and iteration management processes:

• User Expression: "Make a blog", "Develop a calculator", "Implement XX function", "Make an e-commerce system"
• Collaboration Process:

1. COX understands requirements, plans project structure and iterations
2. COX generates observability data (project progress, task list, module planning)
3. COX passes planning to development skills (e.g., cox-coding) for specific implementation
4. COX continuously tracks progress, updates observability data

Sample Dialogue:

User: HI COX, make a calculator
COX: Okay, I'll help you plan the calculator project development. Let me first create project observability data...
[Call script to generate data, plan iterations and tasks]
COX: Project planning completed, including the following modules:
- UI Interface Module
- Calculation Logic Module
- History Record Module
 
Now I'll break down iteration tasks, then ask development skills to implement specific functions.

Project Progress

• "Want to know how project progress is going", "What's the iteration completion rate?"
• "Check task status", "Which tasks are completed", "What's left to do"

Issue Tracking

• "How to track frequent bugs", "How to handle recurring issues", "Need to record issues to resolve"
• "Are there any anomalies that need attention"

Quality Assurance

• "Need to monitor API performance", "How to discover system anomalies", "How's test coverage"
• "API response time slow", "System has anomalies"

Team Collaboration

• "Need to share project information", "Let team members understand current status", "Need visual dashboard"

Deployment Solution Selection

Before starting, please select a deployment solution based on team needs. Detailed configuration instructions are in references/deployment_details.md.

Interactive Web Solution (Recommended)

• Features: Provides local Web interface, supports real-time data refresh (every 30 seconds), supports interaction
• Applicable Scenarios: Real-time monitoring required
• Usage Threshold: Requires Flask installation (pip install flask)
• Usage Method: Call scripts/run_web_observability.py --mode web, access http://localhost:5000

Static Web Solution

• Features: Generates static HTML files, data embedded in HTML, no additional JSON files required
• Applicable Scenarios: Restricted environments (such as online sandbox environments), quick requirement validation
• Usage Threshold: No additional dependencies required (no need to install Flask)
• Usage Method: Call scripts/run_web_observability.py --mode static, generates observability.html file
• Refresh Method: Click refresh button to re-render data (static mode doesn't support auto-refresh)

Comprehensive Solution (Not Available Yet)

• Features: Professional observability tools using Prometheus + Grafana, Docker deployment
• Applicable Scenarios: Preparing to migrate to production environment, requiring professional monitoring capabilities
• Status: Not open yet, will be launched after improving data integration and configuration schemes

Quick Start

Step 0: Mid-Project Onboarding Detection (For Mid-Project COX Invocation)

Before executing any operations, the agent should first detect whether mid-project takeover is needed:

Detection Conditions:

• project_data.json file does not exist
• Current directory contains other files (code, documentation, configuration, etc.)

Execution Flow:

1. Detect Project Content

• Use ls or Glob to check if current directory has files
• If files exist but project_data.json is missing, trigger mid-project onboarding flow

1. Prompt User

`` Detected existing project content, but not yet connected to COX observability system. COX can help you take over project management and continue planning iterations and tasks. ``

1. Ask User (Choose One)

• a) "Do you have project progress documentation (README, plan, TODO, etc.)? Please provide path"
• b) "Tell me directly what features are completed and what issues exist"
• c) "Analyze existing files to automatically infer project progress"

1. Process User Input

• Option a: Read documentation, extract feature list and progress information
• Option b: Parse user description, organize feature list
• Option c: Use Grep, Read to analyze code/documentation structure

1. Generate First Iteration

• Iteration name: ITER-001 - "COX Onboarding - Project Status Review"
• Mark completed features as completed tasks
• Mark issues/pending features as todo or in_progress tasks
• Infer module list based on content

1. Enter Subsequent Flow

• Execute Step 1: Generate complete data files
• Subsequent flow same as normal startup

Sample Dialogue:

Agent: Detected existing project content, but not yet connected to COX observability system.
 
How would you like me to understand current project progress?
a) Provide project progress documentation (README, plan, etc.)
b) Tell me directly about completed and pending features
c) Analyze existing files to automatically infer
 
User: Choose b, I've completed user login and article list features, but comment feature has issues
 
Agent: Understood. I'll generate project data for you:
- Completed: User login, Article list
- Pending fix: Comment feature issues
 
Generating project observability data...

Step 1: Generate Observability Data

Recommended Method: Use Script to Generate Data

To ensure data format 100% complies with specification, recommend using data generation script:

# Method 1: Generate minimal dataset (quick experience)
python scripts/generate_observability_data.py \
  --mode minimal \
  --project-name "My Project" \
  --app-name "My Application"
 
# Method 2: Generate custom modules (recommended)
# Agent should decompose tasks based on actual requirements, not use sample tasks
python scripts/generate_observability_data.py \
  --mode complete \
  --project-name "Calculator Project" \
  --app-name "Calculator Application" \
  --iterations 2 \
  --modules '[{"id":"MOD-001","name":"UI Interface Module"},{"id":"MOD-002","name":"Calculation Logic Module"}]'
 
 
# Method 2.5: Use custom iteration names (recommended)
# Specify meaningful names for each iteration, not default "Iteration N"
python scripts/generate_observability_data.py   --mode complete   --project-name "Calculator Project"   --app-name "Calculator Application"   --iterations 4   --modules '[{"id":"MOD-001","name":"UI Interface Module"},{"id":"MOD-002","name":"Calculation Logic Module"}]'   --iteration-names '["Core Foundation and Platform Configuration","Planning Management and Assumption Management","Content Generation Workflow","Intelligent Assistance and Optimization"]'
 
# Method 3: Generate complete example (includes test suite framework, but tasks, tracing points, anomalies left empty)
python scripts/generate_observability_data.py \
  --mode complete \
  --project-name "Calculator Project" \
  --app-name "Calculator Application" \
  --iterations 2 \
  --modules '[{"id":"MOD-001","name":"UI Interface Module"},{"id":"MOD-002","name":"Calculation Logic Module"}]'

Script generates three JSON files in current directory:

• project_data.json: Project iteration and task data
• app_status.json: Application module status data
• test_metrics.json: Test tracing points and anomaly data

Core Principles:

• Sample data only provides minimal skeleton, doesn't fill any false business data
• Tasks, tracing points, anomalies default to empty, filled by agent based on actual situation
• Everything based on real data, avoid producing misleading information

About Tasks:

• Script Behavior: Default generates empty tasks array, no additional parameters needed. Agent should decompose tasks based on actual requirements then populate.
• Task Fields:
• task_id: Task ID (e.g., TASK-001)
• task_name: Task name (specific description, e.g., "Design calculator UI interface")
• status: Task status (todo/in_progress/completed/delayed)
• assignee: Responsible person (optional, fill when team collaboration needed)
• priority: Priority (low/medium/high/critical)
• tags: Tags (optional, for classification)

About Tracing Points and Anomalies:

• Default Empty: Tracing points and anomalies generated by script are both empty arrays []
• Real Data Filling: Should be filled by agent based on actual monitoring data
• Data Fields:
• tracing_points: Test tracing points (module, location, status, metric type)
• anomalies: Anomaly records (type, description, severity, status, occurrence count, time)

Custom Module Explanation:

• Use --modules parameter to define modules actually needed by project
• Module list in JSON format, containing id and name fields
• When calling script, agent should automatically infer suitable modules based on project requirements

⚠️ Key Rule: Module Definition Rule

• Modules must be user-verifiable functions, not technical components
• Prohibited Module Names: "UI Module", "Backend Module", "Database Module", "Logic Module", "Interface Module", etc.
• Correct Module Examples: "User Login", "Article List", "Add to Cart", "Search", "Payment"
• Think from user perspective: "What can I see and test?" not "How is it implemented?"

Subsequent Usage:

• Directly modify generated JSON files to adapt to actual project
• Data format instructions in references/data_format.md

Step 2: Select Solution and Start

Interactive Web Solution (Recommended):

# Start Web server (need to install Flask first: pip install flask)
python scripts/run_web_observability.py \
  --mode web \
  --project project_data.json \
  --app app_status.json \
  --test test_metrics.json \
  --host 127.0.0.1 \
  --port 5000
 
# Access http://127.0.0.1:5000 to view interface, data auto-refreshes every 30 seconds

Static Web Solution:

# Generate static HTML file (no Flask required)
# Data will be inlined to HTML, no additional JSON files needed
python scripts/run_web_observability.py \
  --mode static \
  --project project_data.json \
  --app app_status.json \
  --test test_metrics.json \
  --output observability.html
 
# Directly open observability.html in browser to view interface
# Data inlined, no other files needed

Explanation:

• Web mode: Data updates in real-time, no regeneration needed, access http://127.0.0.1:5000 to view interface
• Static mode: Data inlined to HTML file, generate once then data fixed, click refresh button to re-render

Step 3: Call skill-manager to store deployment information

After deployment, call skill-manager skill to store deployment information, facilitate subsequent management and skill collaboration.