DOCSEARCHbyAlgolia
Submit Docs

Long-Task Agent for Claude Code

repository·main·Indexed 41 days ago

https://github.com/suriyel/longtaskforagent

A Claude Code skill plugin that transforms single-session AI coding into a multi-session software engineering workflow. It utilizes a seven-stage architecture (Requirement, UCD, Design, ATS, Initialization, Work Loop, and System Test) and persistent state artifacts like feature-list.json to maintain context across sessions. The agent supports TDD, industry-standard documentation (ISO/IEC/IEEE 29148, 29119), and custom MCP tool bindings for enterprise environments.

Tokens
109.3K
Snippets
156
Records
339
Agent score
51%

What's inside Long-Task Agent

  1. Multi-Language Coverage and Mutation Tool Matrix

    main

    Use this matrix to identify the recommended coverage and mutation testing tools for your project's language. It includes details on branch support and incremental testing capabilities.

    | Language | Coverage Tool | Branch Support | Mutation Tool | Incremental Support |
|----------|--------------|---------------|---------------|---------------------|
| Python | pytest-cov (coverage.py) | Yes | mutmut | Yes (`--paths-to-mutate`) |
| Java | JaCoCo | Yes | PIT (pitest) | Yes (`-DtargetClasses`) |
| JavaScript | c8 / nyc (Istanbul) | Yes | Stryker | Yes (`--mutate` glob) |
| TypeScript | c8 / nyc (Istanbul) | Yes | Stryker | Yes (`--mutate` glob) |
| C | gcov + lcov | Yes (`--branch-probabilities`) | Mull | Partial (filter by file) |
| C++ | gcov + lcov / llvm-cov | Yes | Mull | Partial (filter by file) |

  2. Use the long-task-explore skill for codebase exploration

    main

    The long-task-explore skill is used for on-demand, deep exploration of an existing codebase. It analyzes architecture, data flow, domain models, API surfaces, dependencies, and code health to produce a structured understanding document.

    Invocation Modes

    • Standalone: Operates independently without pipeline state or skill chaining.
    • Pipeline: Called from within pipeline phases (e.g., requirements, increment). The calling skill provides focus direction and depth, and the exploration results are fed back to the caller.

    Critical Constraints

    • Read-only: Do NOT modify any source code, tests, or configuration files.
    • No Judgment: Do NOT suggest improvements, critique implementations, or recommend refactoring. Only describe what exists and how components interact.
    • Evidence-based: All technical claims must cite file:line evidence.
    • Isolation: Never read or write pipeline artifacts (e.g., feature-list.json, SRS, design docs).

  3. Understand the Long-Task Agent project structure

    main

    The project is organized into specialized 'skills' that follow a seven-phase development lifecycle. These skills are loaded on-demand to guide an agent through requirements, design, implementation, and testing.

    Key directories include:

    • skills/: Contains the core logic for each development phase (e.g., long-task-requirements, long-task-design, long-task-work).
    • commands/: Contains user shortcut commands for interacting with the agent.
    • docs/templates/: Provides customizable templates for Software Requirements Specifications (SRS) and design documents.
    • hooks/: Contains SessionStart hook configurations.
    • scripts/: Utility and validation scripts.
    long-task-agent/
├── skills/                          # 13 skills (on-demand loaded)
│   ├── using-long-task/             # Bootstrap router
│   ├── long-task-requirements/      # Phase 0a: Requirements & SRS
│   ├── long-task-ucd/               # Phase 0b: UCD style guide
│   ├── long-task-design/            # Phase 0c: Design
│   ├── long-task-ats/               # Phase 0d: Acceptance Test Strategy
│   ├── long-task-init/              # Phase 1: Initialization
│   ├── long-task-work/              # Phase 2: Worker orchestrator
│   ├── long-task-tdd/               # TDD discipline
│   ├── long-task-quality/           # Coverage + mutation gates
│   ├── long-task-feature-st/        # Per-feature black-box acceptance testing
│   ├── long-task-increment/         # Incremental development
│   ├── long-task-st/                # System testing
│   └── long-task-finalize/          # Post-ST documentation & examples
├── scripts/                         # Validation & utility scripts
├── tests/                           # Test suite for all scripts
├── hooks/                           # SessionStart hook config
├── commands/                        # User shortcut commands
└── docs/templates/                  # Customizable SRS & design templates

  4. Scale Design Depth based on Project Size

    main

    Adjust the depth of your design documentation based on the number of features in the project to manage context window constraints and complexity.

    Design Depth by Project Size

    Project SizeFeaturesDesign Depth
    Tiny1-5Single paragraph approach + 1 approval step; logical view + 1 feature diagram + dependency table + simplified dev plan
    Small5-202-3 approach options + combined section approval; logical view + key feature diagrams + dependency table + milestone plan
    Medium20-50Full multi-section approval; all architecture views + per-feature diagrams + full dependency analysis + detailed dev plan
    Large50-200+Full multi-section approval; comprehensive diagrams for every feature group + dependency compatibility matrix + phased dev plan with risk register

    Section 4 (§4.N) Content Strategy

    For projects with many features, use different depths for the feature sections (§4.N):

    • Small (< 20 features): Full detail (overview + class diagram + behavioral diagram + design notes + integration surface).
    • Medium (20-50 features): Full detail for P0/P1 features; Thin format for P2/P3 features.
    • Large (50+ features): Thin format for ALL features (overview + key types + integration surface only).

    Thin §4.N format:

    ### 4.N Feature: <Name> (FR-xxx)
#### 4.N.1 Overview
[1-2 sentences]
#### 4.N.2 Key Types
[List the main classes/types this feature introduces, with one-line purpose each]
#### 4.N.6 Integration Surface
[Provides/Requires tables referencing §6.2]

  5. Select dimensions for Behavior Hypothesis Tables by FR Type

    main

    Not all 8 behavioral dimensions apply to every Functional Requirement (FR). To maintain efficiency, select dimensions based on the FR type:

    • Read-only display: Include dimensions 1, 3, 4, 5. Skip 2, 6, 7.
    • Data entry / form: Include dimensions 1, 2, 3, 4, 5, 7. Skip 6 (unless multi-user editing is likely).
    • State-changing action: Include dimensions 1, 2, 4, 5, 6, 7. Skip 3 (unless batch processing).
    • Background process: Include dimensions 1, 4, 7. Skip 2, 3, 5, 6.
    • Integration / API: Include dimensions 1, 3, 4, 8. Skip 5 (unless user-facing), 6, 7.

    Note: Always include dimension 8 (Negative scope) for complex FRs where boundaries are ambiguous.

  6. The long-task-work execution pipeline

    main

    The long-task-work skill operates on the principle of "One Feature Per Cycle." Each cycle follows a specific orchestration order of sub-steps. Each sub-step is intended to be handled by its own specialized skill.

    The pipeline order is:

    1. Orient: Initial orientation.
    2. Bootstrap: Setting up the environment.
    3. Config Gate: Configuration validation.
    4. Feature Detailed Design: Planning the feature.
    5. TDD Cycle: The core development loop consisting of Red → Green → Refactor.
    6. Quality Gates: Ensuring code meets standards.
    7. ST Acceptance Test Cases: Verifying against acceptance criteria.
    8. Inline Compliance Check: Ensuring no unauthorized SubAgents were used.
    9. Persist: Saving state for the next session.

  7. Git Worktree Isolation Rules

    main

    When managing feature development via worktrees, adhere to these strict rules:

    • Always verify .gitignore includes the worktree directory.
    • Always run baseline tests before starting work in a new worktree.
    • Never force-delete a worktree without explicit user confirmation.
    • If the user declines worktree isolation, work directly on a feature branch (ensuring it is still isolated from main).

  8. Understand the ATS Document Structure

    main

    The Acceptance Test Strategy (ATS) document is a structured blueprint used by the LLM to ensure all requirements are covered by tests. The standard structure includes:

    • Document Header: Metadata including SRS/Design/UCD references and status.
    • Section 1: Test Scope & Strategy Overview: Defines testing goals, quality targets (e.g., mandatory categories like FUNC, BNDRY, SEC), and testing levels (Unit, Feature-ST, System-ST).
    • Section 2: Requirement → Acceptance Scenario Mapping: The core mapping of Functional Requirements (FR), Non-Functional Requirements (NFR), and Interface Requirements (IFR) to specific test scenarios and categories.
    • Section 3: Test Category Strategies: Specific methodologies for different test types (FUNC, BNDRY, SEC, PERF, UI).
    • Section 4: NFR Test Method Matrix: Detailed tools and pass/fail criteria for non-functional requirements.
    • Section 5: Cross-Feature Integration Scenarios: Scenarios covering data flows between multiple features.
    • Section 6: Risk-Driven Test Priority: Risk assessment and definitions of testing depth (Deep, Standard, Lightweight).
    • Appendix: Review reports generated by the ats-reviewer subagent.

  10. Define UCD Style Tokens (Color, Typography, Spacing)

    main

    The UCD style guide requires defining concrete design tokens to ensure visual consistency.

    Color Palette

    Tokens must include Hex codes, usage descriptions, and contrast ratios. All colors MUST meet WCAG AA minimums (4.5:1 for normal text, 3:1 for large text). If SRS specifies WCAG AAA, use 7:1 / 4.5:1.

    Typography Scale

    Define font family, size, weight, line height, and usage for elements like heading-1, body, label, and code.

    Spacing & Layout

    Define tokens for padding (--space-xs to --space-xl), border radii (--radius-sm to --radius-lg), and shadows (--shadow-sm to --shadow-lg).

    | Token | Hex | Usage | Contrast Ratio |
|-------|-----|-------|----------------|
| --color-primary | #XXXXXX | Primary actions, links, active states | >= 4.5:1 on white |
| --color-text-primary | #XXXXXX | Body text | >= 4.5:1 on bg-primary |

| Token | Font Family | Size | Weight | Line Height | Usage |
|-------|-------------|------|--------|-------------|-------|
| --font-body | [family] | [size] | [weight] | [lh] | Body text |

| Token | Value | Usage |
|-------|-------|-------|
| --space-md | [value] | Section gaps |
| --radius-md | [value] | Cards |

  11. Follow the Skip-Explicitly Rule for Design Completeness

    main

    To prevent design defects that block TDD, every section of the design document (§2-§6) must follow the Skip-Explicitly Rule. A section cannot be left empty or half-filled. It must either:

    1. Contain COMPLETE content according to the specified requirements.
    2. State exactly: N/A — [specific reason why this section does not apply].

    An empty section or a section stating N/A without a justification is considered a design defect.

  12. How Long-Task Agent bridges sessions with persistent state

    main

    Long-Task Agent solves the problem of AI losing context after a /clear command by using ten+ persistent artifacts. These artifacts ensure zero knowledge loss between sessions by acting as a source of truth for the project state.

    Key Persistent Artifacts

    ArtifactPurpose
    feature-list.jsonStructured task inventory with status tracking
    task-progress.mdSession-by-session log with current state header
    docs/plans/*-srs.mdApproved Software Requirements Specification
    docs/plans/*-design.mdApproved technical design document
    docs/plans/*-ats.mdApproved Acceptance Test Strategy
    docs/plans/*-ucd.mdApproved UCD style guide (UI projects)
    docs/test-cases/feature-*.mdPer-feature ST test case documents
    RELEASE_NOTES.mdLiving changelog in Keep a Changelog format
    Git historyFull change history with descriptive commits