suriyel/longtaskforagent/long-task-work

Worker — One Feature Per Cycle

Execute multi-session software projects by implementing one feature per cycle. Each cycle follows a strict pipeline: Orient → Gate → Plan → TDD → Quality → ST Acceptance → Inline Check → Persist.

Announce at start: "I'm using the long-task-work skill. Let me orient myself."

Core principle: Each sub-step has its own skill. Follow the orchestration order exactly.

Checklist

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

1. Orient

• Load config values if applicable — activate the project environment per long-task-guide.md; if the project uses a file-based config (e.g., .env), ensure it is sourced so required env vars are set before running checks
• Read task-progress.md ## Current State section — progress stats, last completed feature, next feature up
• Read feature-list.json — note constraints[], assumptions[], required_configs[], feature statuses
• Read long-task-guide.md — project-specific workflow guidance
• Read env-guide.md (if it exists) — note service names, ports, and health check URLs; required if the target feature has service dependencies
• Determine service dependencies: A feature has service dependencies if ANY of the following are true:

1. Its required_configs[] entries include connection-string keys (key contains URL, URI, DSN, CONNECTION, HOST, or PORT — e.g., DATABASE_URL, REDIS_HOST)
2. Its dependencies[] include a feature whose title references database setup, schema migration, or service initialization
3. The design section ({design_section}) specifies external service interactions (DB queries, HTTP calls to own services, message queue operations)

Record determination (yes/no + which services) in task-progress.md under the current feature heading. This determination drives Bootstrap Step 2 and Config Gate Step 3.

• Read design doc Section 1 (docs/plans/*-design.md) — project overview and architecture snapshot for global context
• Read design doc §13 (Codebase Conventions & Constraints, if exists) — note 2/3方件 library constraints (§13.1), prohibited APIs (§13.2), static analysis tools (§13.4), naming conventions (§13.5), error handling pattern (§13.6), commit conventions (§13.8). These are binding for all new code.
• Run git log --oneline -10 — recent commit context
• Pick next "status": "failing" feature by priority, then by array position in features[] (first eligible wins) — skip features with `"deprecated": true`
• Dependency satisfaction check: After selecting a candidate feature, verify that ALL feature IDs in its dependencies[] have "status": "passing" in feature-list.json. If any dependency is still "failing":
• Log: "Feature #{id} ({title}) skipped — unsatisfied deps: #{dep1}, #{dep2}"
• Pick the next eligible "failing" feature (by priority + dependency order) whose dependencies are all satisfied
• If NO features have all dependencies satisfied → warn user via AskUserQuestion: "All remaining features have unsatisfied dependencies. Circular or over-constrained dependency graph detected." → let user choose which feature to force-start (override dependency check)
• Record skipped features and reason in task-progress.md
• If target feature has "ui": true and UCD document exists (docs/plans/*-ucd.md), read the UCD style guide — reference style tokens, component prompts, and page prompts to ensure frontend implementation matches the approved visual style

Document Lookup Protocol (used by Steps 5, 10, and 11):

When you need the design section or SRS requirement for a feature, do NOT grep for the feature title. Instead:

1. Design document (docs/plans/*-design.md):

• Read the design document's Section 4 heading area (use Read tool with offset/limit to scan section 4 headers — look for lines matching ### 4.N Feature:)
• Identify which ### 4.N subsection corresponds to the target feature by matching the feature title or FR-ID
• Read the entire subsection from ### 4.N through the line before ### 4.(N+1) (or end of section 4) — this includes Overview, Class Diagram, Sequence Diagram, Flow Diagram, and Design Decisions
• Store this full text as {design_section} for use in Plan (Step 5) and ST Acceptance (Step 9)

1. SRS document (docs/plans/*-srs.md):

• Read the SRS Section 4 (Functional Requirements) heading area to find the ### FR-xxx subsection matching the target feature
• Read the entire FR-xxx subsection including EARS statement, priority, acceptance criteria, and Given/When/Then scenarios
• Store this as {srs_section} for use in Plan

1. UCD document (docs/plans/*-ucd.md, only for "ui": true features):

• Read the UCD's table of contents or section headers
• Find sections referencing the target feature's UI components or pages
• Read the full relevant sections including style tokens, component prompts, and page prompts

Why this matters: Grep returns isolated matching lines without surrounding context. Design sections contain class diagrams, sequence diagrams, flow diagrams, and design rationale that span dozens of lines — all of which are needed for correct implementation and inline compliance checking.

2. Bootstrap

• Development environment readiness: Check if environment is set up
• If init.sh / init.ps1 exists and environment is not ready: run it once
• Record decision in task-progress.md if script was executed
• Confirm test commands available: Activate environment per long-task-guide.md and verify the test/coverage/mutation commands are correct for the tech stack; use these directly throughout the cycle (no wrapper scripts)
• Service readiness (conditional — based on Orient service dependency determination):
• No service dependencies: Skip service startup. Feature-ST (Step 10) manages services for acceptance testing.
• Has service dependencies: Real tests (TDD Rule 5a) need running infrastructure. Ensure availability:

1. Read env-guide.md → locate "Verify Services Running" health checks
2. Run health checks. If all pass → record PID/port in task-progress.md; proceed
3. If health checks fail → start via env-guide.md "Start All Services" with output capture:

``bash [start command] > /tmp/svc-<slug>-start.log 2>&1 & sleep 3 head -30 /tmp/svc-<slug>-start.log ``

1. Re-run health checks — block until pass
2. If start fails → diagnose per env-guide.md; escalate via AskUserQuestion if unresolvable
3. Record running services, PIDs, ports in task-progress.md

• Feature-ST (Step 10) handles restart/cleanup. Services started here remain running through TDD and Quality Gates.
• Smoke-test previously passing features (activate environment per long-task-guide.md → run test command directly)

3. Config Gate

python scripts/check_configs.py feature-list.json --feature <id>

<id> = the feature ID selected in Step 1. The generated check_configs.py loads config values using the project's native format automatically.

If configs are missing — prompt for text input and save to the project config:

1. For each missing env-type config, use AskUserQuestion to ask the user to type the value — do NOT provide predefined option buttons. Frame the question with the config's name, description, and check_hint so the user knows what to provide.

• Example: "Please enter the value for OPENAI_API_KEY (OpenAI API key for LLM integration). Hint: Get it from https://platform.openai.com/api-keys"

1. For each missing file-type config, ask the user to provide the file path or create the file manually.
2. After receiving all values, save env-type configs following the project's config format — refer to the Config Management section in long-task-guide.md for the exact method (e.g., append to .env, set in application.properties, export as system env var).
3. Re-run the check to confirm:

``bash python scripts/check_configs.py feature-list.json --feature <id> ``

1. Ensure any secrets config file is listed in .gitignore if not already present.
2. Block until all configs pass.
3. Connectivity verification (features with service dependencies only):

After config keys pass existence checks, verify connection-string configs actually connect:

• For each env-type config whose key matches a connection-string pattern (DATABASE_URL, REDIS_URL, etc.): run the corresponding health check from env-guide.md "Verify Services Running"
• If health check fails: config value exists but service is unreachable — start service per Bootstrap service readiness protocol above
• Block until connectivity confirmed — a config pointing to a dead service is functionally missing

Config Gate is non-negotiable for features with external dependencies. If configs are missing:

• MUST use AskUserQuestion to request values from the user
• MUST NOT proceed to TDD without all configs resolved
• MUST NOT claim "pure-function exemption" for features that have required_configs[] entries with connection-string keys (URL, HOST, PORT, DSN, URI, CONNECTION, ENDPOINT)
• Quality Gates (Gate 0) will mechanically enforce this via check_real_tests.py --require-for-deps

4. Feature Detailed Design

REQUIRED SUB-SKILL: Invoke long-task:long-task-feature-design and follow it exactly.

The Feature Design skill dispatches a SubAgent to produce the detailed design document. The main Agent does NOT read design/SRS/UCD document sections or write the design document — the SubAgent handles everything in its own fresh context and returns a structured summary.

For `category: "bugfix"` features: feature-design is condensed. The SubAgent focuses on: (1) root cause documentation, (2) targeted fix approach, (3) regression test inventory. Full diagrams are skipped unless the bug directly touches those surfaces.

Context to carry forward (paths only — SubAgent reads contents itself):

• Feature object (compact JSON)
• quality_gates and tech_stack (compact JSON)
• File paths + section line ranges: design doc (§4.N), SRS doc (FR-xxx), UCD doc (if ui:true)
• ATS doc path: docs/plans/*-ats.md (if exists) — SubAgent uses ATS mapping to align Test Inventory categories
• Design doc §6.2 path — SubAgent reads Internal API Contracts rows where this feature is Provider or Consumer
• Constraints and assumptions from feature-list.json root
• Output path: docs/features/YYYY-MM-DD-<feature-name>.md

Output: docs/features/YYYY-MM-DD-<feature-name>.md (written by SubAgent) — feature detailed design document containing interface contracts, algorithm pseudocode, diagrams, test inventory, and TDD task decomposition.

Contract deviation handling: If SubAgent returns BLOCKED with an issue containing "Contract deviation":

1. Present the deviation details (Contract ID, original vs. proposed schema, reason) to user via AskUserQuestion
2. If approved: update §6.2 in the design doc to reflect the new contract, then re-dispatch the feature-design SubAgent
3. Propagate impact: identify Consumer features from the §6.2 Consumer column that may be affected; if any are already "passing", warn user they may need re-verification