suriyel/longtaskforagent/long-task-init

LANGUAGE RULE: You MUST respond to the user in Chinese (Simplified). All generated documents, reports, and user-facing output must be written in Chinese. Skill names, code identifiers, and JSON field names remain in English.

Initialize Long-Task Project

Run once after both SRS and design are approved. Scaffolds all persistent artifacts, populates features from Design §10.2 (FRs already right-sized at Requirements phase), and prepares the project for iterative Worker cycles.

Announce at start: "I'm using the long-task-init skill to scaffold the project."

Input Documents

This skill reads from three approved documents:

Checklist

You MUST create a TodoWrite task for each step and complete them in order:

1. Read the approved SRS, design, and ATS documents from docs/plans/

• SRS: docs/plans/*-srs.md — for requirements, constraints, assumptions, NFRs, glossary, personas
• Design: docs/plans/*-design.md — for tech stack, architecture decisions
• ATS: docs/plans/*-ats.md — for requirement→category mapping (constrains ui flag and downstream feature-st category requirements via srs_trace)

1. Run `scripts/init_project.py` to scaffold deterministic artifacts:

``bash python scripts/init_project.py <project-name> --path . --lang <language> ``

• <project-name> — from the SRS title
• <language> — one of python|java|typescript|c|cpp from the design doc tech stack
• Use --line-cov, --branch-cov, --mutation-score to override thresholds (defaults: 90/80/80)
• Creates: feature-list.json, CLAUDE.md (appended), task-progress.md, RELEASE_NOTES.md, examples/, docs/plans/
• Auto-copies helper scripts (validate_features.py, check_configs.py, check_devtools.py, check_jinja2.py, check_real_tests.py, validate_guide.py, get_tool_commands.py, validate_st_cases.py, validate_increment_request.py, validate_bugfix_request.py, check_st_readiness.py, check_ats_coverage.py, check_mcp_providers.py) into project scripts/

3b. MCP Provider Setup (SKIP if no enterprise MCP required):

• Ask user: "Does this project use enterprise MCP servers for test/coverage/mutation/UI automation?"
• If YES:

1. Collect per capability: MCP server name, install command, tool names, result field paths
2. Create tool-bindings.json at project root using docs/templates/tool-bindings-template.json as a guide
3. Check Jinja2 availability (required for template rendering):

``bash python scripts/check_jinja2.py ` → Exit 1: present installation guide to user (pip install jinja2`); wait for user to install; re-run check to confirm exit 0 → Exit 0: continue

1. Render skill templates:

``bash python scripts/apply_tool_bindings.py tool-bindings.json --output-dir .long-task-bindings `` → Verify: "N templates rendered to .long-task-bindings/"

1. Check MCP server availability:

``bash python scripts/check_mcp_providers.py tool-bindings.json ` → Exit 1: present installation instructions to user (the script outputs exact claude mcp add` commands); wait for user to install and restart session; re-run check to confirm exit 0 → Exit 0: continue

• If NO: skip (skills use plugin defaults — Chrome DevTools MCP for UI, CLI tools for testing)

1. Verify `tech_stack` and `quality_gates` in feature-list.json:

• Confirm language, test_framework, coverage_tool, mutation_tool match the design doc
• Adjust quality_gates thresholds if needed (defaults: line 90%, branch 80%, mutation 80%)
• Verify tool commands resolve correctly:

``bash python scripts/get_tool_commands.py feature-list.json ``

• Verify real_test config in feature-list.json:
• marker_pattern matches the project's chosen real test identification method
• mock_patterns covers the project's mock framework keywords
• test_dir points to the correct test directory

1. Generate `long-task-guide.md` — Create a project-tailored Worker session guide:

• Read these files for reference:
• skills/long-task-work/SKILL.md — Worker workflow
• skills/long-task-quality/SKILL.md — verification enforcement
• skills/long-task-quality/coverage-recipes.md — coverage/mutation tool setup
• skills/using-long-task/references/architecture.md — TDD workflow details
• Include ONLY the project's language-specific coverage/mutation commands (get from python scripts/get_tool_commands.py feature-list.json)
• Include UI testing section ONLY if the project has UI features ("ui": true):
• If tool-bindings.json exists and capability_bindings.ui_tools.tool_mapping is present: use the enterprise tool names from tool-bindings.json throughout the guide (not Chrome DevTools MCP names)
• Otherwise: use Chrome DevTools MCP tool names (navigate_page, click, etc.)
• Must include all required sections: Orient, Bootstrap, Config Gate, TDD Red, TDD Green, Coverage Gate, TDD Refactor, Mutation Gate, Verification Enforcement, Inline Compliance Check, Persist, Critical Rules
• Must include `Environment Commands` section with:
• Environment activation command (e.g., source .venv/bin/activate, conda activate myenv, nvm use 20)
• Direct test execution command (e.g., pytest --cov=src tests/)
• Direct mutation testing command (e.g., mutmut run)
• Direct coverage report command
• These replace the now-removed test.sh/mutate.sh wrappers — Claude runs these directly
• Must include `Service Commands` section (only if project has server processes): reference env-guide.md as the authoritative source for start/stop/restart commands; list health check URLs; include reminder about the Restart Protocol
• Must include `Config Management` section: describe how to add/update a config value for this project (e.g., "append KEY=value to .env" for dotenv projects, "set key=value in application.properties" for Spring Boot projects, "export KEY=value" for system-env-only projects). This section is referenced by the Worker Config Gate when prompting users for missing values.
• Must include `Real Test Convention` section: identification method (marker/folder/naming, adapted to project language), run command to execute only real tests, example real test for this project's tech stack
• Validate:

``bash python scripts/validate_guide.py long-task-guide.md --feature-list feature-list.json ``

1. Generate `env-guide.md` — Create an explicit service lifecycle guide at the project root (user-editable):

• Read the design doc for service port declarations, health check URLs, and service names (API design / architecture sections)
• Read .env.example for *_PORT= variables
• Generate env-guide.md with the following sections:

Header note (top of file): > User-editable. Claude reads this file before managing services. Update when ports change or new services are added.

Services table:

Start All Services — for each service: ```bash # Unix/macOS [start command] > /tmp/svc-<slug>-start.log 2>&1 & sleep 3 head -30 /tmp/svc-<slug>-start.log # → Extract PID and port from output; record both in task-progress.md

# Windows alternative cmd /c "start /b [command] > %TEMP%\svc-<slug>-start.log 2>&1" timeout /t 3 /nobreak >nul powershell "Get-Content $env:TEMP\svc-<slug>-start.log -TotalCount 30" ```

Verify Services Running — for each service: ``bash curl -f http://localhost:<port>/health # or appropriate health endpoint ``

Stop All Services — kill by PID (primary) or port (fallback): ```bash # By PID (preferred — use PID recorded in task-progress.md) kill <PID> # Unix/macOS taskkill /F /PID <PID> # Windows

# By port (fallback) lsof -ti :<port> | xargs kill -9 # Unix/macOS for /f "tokens=5" %a in ('netstat -ano ^| findstr :<port>') do taskkill /F /PID %a # Windows ```

Verify Services Stopped — ports must show no output: ``bash lsof -i :<port> # Unix/macOS — expect no output netstat -ano | findstr :<port> # Windows — expect no output ``

Restart Protocol (4 steps):

1. Kill — Stop All Services (by PID from task-progress.md, or by port)
2. Verify dead — run Verify Services Stopped; poll port max 5 seconds — must not respond
3. Start — run Start All Services with output capture → head -30 → extract new PID/port → update task-progress.md
4. Verify alive — run Verify Services Running; poll health endpoint max 10 seconds — must respond

• Complex startup sequences: if a service requires >2 shell commands to start (e.g., DB migration + seed + server), generate scripts/svc-<slug>-start.sh / scripts/svc-<slug>-start.ps1 containing the full sequence; update env-guide.md "Start All Services" to call bash scripts/svc-<slug>-start.sh instead of inline commands; same for stop sequences (scripts/svc-<slug>-stop.sh). This keeps env-guide.md readable while versioning the logic in scripts/
• If the project is CLI-only or library-only (no server processes): generate a minimal env-guide.md with a header note "No server processes — environment activation only" and only the activation command from long-task-guide.md